diff --git a/.claude/launch.json b/.claude/launch.json
new file mode 100644
index 00000000..4cd6bdd3
--- /dev/null
+++ b/.claude/launch.json
@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "oneagent-frontend",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["--prefix", "frontend", "run", "dev"],
+      "port": 5173
+    }
+  ]
+}
diff --git a/.dockerignore b/.dockerignore
index 0297ee6c..594ea4b1 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -1,20 +1,16 @@
 .git
 .gitignore
 .env*
-.venv
-venv
-__pycache__
-*.py[cod]
 *.key
 *.pem
 *.p12
 auth.json
 .npmrc
-.pypirc
 .netrc
 .docker
 .aws
 .qoder
+bin
 .codex
 .claude
 .oneagent
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
deleted file mode 100644
index ffb4f49f..00000000
--- a/.github/workflows/ci.yml
+++ /dev/null
@@ -1,210 +0,0 @@
-name: CI
-
-on:
-  # Automatic runs are off at the repository owner's request. The jobs below are
-  # unchanged and still run on demand from the Actions tab, so restoring
-  # continuous checks means putting the pull_request and push triggers back --
-  # nothing else here has to change.
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  container-cleanroom:
-    name: Docker Linux cleanroom
-    runs-on: ubuntu-22.04
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Build and run isolated Linux cleanroom
-        run: bash scripts/test_docker_cleanroom.sh
-
-      - name: Upload cleanroom evidence
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: docker-linux-cleanroom
-          path: build/docker-cleanroom
-          if-no-files-found: ignore
-
-  contract-and-browser:
-    name: ${{ matrix.label }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-22.04
-            label: Linux x64
-          - os: windows-2022
-            label: Windows x64
-          - os: macos-15
-            label: macOS arm64
-          - os: macos-15-intel
-            label: macOS x64
-    runs-on: ${{ matrix.os }}
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "22"
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
-
-      - name: Install Python test tools
-        run: python -m pip install coverage==7.15.2
-
-      - name: Install macOS packaging tool
-        if: runner.os == 'macOS'
-        run: python -m pip install pyinstaller==6.21.0
-
-      - name: Install frontend dependencies
-        working-directory: frontend
-        run: npm ci
-
-      - name: Build frontend
-        working-directory: frontend
-        run: npm run build
-
-      - name: Python contracts and coverage
-        shell: bash
-        run: |
-          mkdir -p build/coverage
-          coverage erase
-          coverage run --branch -m unittest tests.test_core tests.test_cli tests.test_server tests.test_release_policy tests.test_distribution_data tests.test_edge_cases tests.test_rc_scripts tests.test_install_contract tests.test_config_discovery
-          coverage report --fail-under=85
-          coverage json
-          python -c "import json, os; files = json.load(open('build/coverage/coverage.json', encoding='utf-8'))['files']; normalized = {key.replace(os.sep, '/'): value for key, value in files.items()}; summary = normalized['oneagent/installer.py']['summary']; assert summary['percent_branches_covered'] == 100 and summary['num_partial_branches'] == 0, summary"
-
-      - name: Bash compatibility contracts
-        if: runner.os != 'Windows'
-        run: bash tests/install_test.sh
-
-      - name: GUI compatibility smoke
-        if: runner.os != 'Windows'
-        run: python tests/gui_smoke_test.py
-
-      - name: PowerShell wrapper contract
-        if: runner.os == 'Windows'
-        shell: pwsh
-        run: |
-          $homeDir = Join-Path $env:RUNNER_TEMP "oneagent-contract-home"
-          ./scripts/install.ps1 --agent openclaw --check-agent-only --json --home $homeDir
-
-      - name: Wheel builds and runs from a clean install
-        run: python scripts/verify_wheel.py
-
-      - name: React unit coverage
-        working-directory: frontend
-        run: npm run test:coverage
-
-      - name: Install Chromium
-        working-directory: frontend
-        run: npx playwright install chromium
-
-      - name: Browser E2E
-        working-directory: frontend
-        run: npm run e2e
-
-      - name: Build native macOS onedir
-        if: runner.os == 'macOS'
-        run: python scripts/build_release.py --channel technical-preview-unsigned --skip-frontend
-
-      - name: Real macOS cleanroom
-        if: runner.os == 'macOS'
-        env:
-          ONEAGENT_PACKAGED_BINARY: ${{ github.workspace }}/build/pyinstaller-dist/OneAgent/OneAgent
-        run: bash tests/macos_cleanroom_test.sh
-
-      - name: Validate macOS arm64 release for the public site
-        if: matrix.os == 'macos-15'
-        run: python scripts/check_release.py release
-
-      - name: Upload verified macOS arm64 release for the public site
-        if: matrix.os == 'macos-15'
-        uses: actions/upload-artifact@v4
-        with:
-          name: public-site-release-macos-arm64
-          path: release/*
-          if-no-files-found: error
-
-      - name: Upload browser failures
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: browser-failures-${{ matrix.os }}
-          path: frontend/test-results
-          if-no-files-found: ignore
-
-      - name: Upload macOS cleanroom failures
-        if: failure() && runner.os == 'macOS'
-        uses: actions/upload-artifact@v4
-        with:
-          name: macos-cleanroom-failures-${{ matrix.os }}
-          path: build/macos-cleanroom
-          if-no-files-found: ignore
-
-
-  public-site:
-    name: Public distribution site
-    needs: contract-and-browser
-    runs-on: ubuntu-22.04
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Download verified macOS arm64 release
-        uses: actions/download-artifact@v4
-        with:
-          name: public-site-release-macos-arm64
-          path: release
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "22"
-          cache: npm
-          cache-dependency-path: site/package-lock.json
-
-      - name: Install site dependencies
-        working-directory: site
-        run: npm ci
-
-      - name: Unit, type and release-data checks
-        working-directory: site
-        run: |
-          npm test
-          npm run build
-
-      - name: Install Chromium
-        working-directory: site
-        run: npx playwright install --with-deps chromium
-
-      - name: Browser and accessibility checks
-        working-directory: site
-        run: npm run test:e2e
-
-      - name: Verify GitHub Pages base path build
-        working-directory: site
-        env:
-          SITE_URL: https://example.com
-          BASE_PATH: /OneAgent
-        run: npm run build
-
-      - name: Upload site browser failures
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: public-site-browser-failures
-          path: site/test-results
-          if-no-files-found: ignore
diff --git a/.github/workflows/release-candidate.yml b/.github/workflows/release-candidate.yml
deleted file mode 100644
index 427a333c..00000000
--- a/.github/workflows/release-candidate.yml
+++ /dev/null
@@ -1,153 +0,0 @@
-name: Release Candidate Verification
-
-on:
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  native-build-and-agent-install:
-    name: ${{ matrix.label }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-22.04
-            label: Linux x64
-            source: "--source"
-          - os: windows-2022
-            label: Windows x64
-            source: ""
-          - os: macos-15
-            label: macOS arm64
-            source: ""
-          - os: macos-15-intel
-            label: macOS x64
-            source: ""
-    runs-on: ${{ matrix.os }}
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - uses: astral-sh/setup-uv@v7
-        with:
-          version: "0.11.20"
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "22"
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
-
-      - name: Install build dependencies
-        run: python -m pip install pyinstaller==6.21.0
-
-      - name: Build frontend
-        working-directory: frontend
-        run: |
-          npm ci
-          npm run test:coverage
-          npm run build
-
-      - name: Run Python contracts
-        run: python -m unittest tests.test_core tests.test_cli tests.test_server tests.test_release_policy tests.test_edge_cases tests.test_rc_scripts tests.test_install_contract tests.test_config_discovery
-
-      - name: Build unsigned native package
-        shell: bash
-        run: python scripts/build_release.py --channel technical-preview-unsigned --skip-frontend ${{ matrix.source }}
-
-      - name: Smoke packaged executable on Unix
-        if: runner.os != 'Windows'
-        shell: bash
-        run: |
-          home_dir="$(mktemp -d)"
-          build/pyinstaller-dist/OneAgent/OneAgent --agent openclaw --check-agent-only --json --home "$home_dir"
-
-      - name: Real macOS cleanroom
-        if: runner.os == 'macOS'
-        env:
-          ONEAGENT_PACKAGED_BINARY: ${{ github.workspace }}/build/pyinstaller-dist/OneAgent/OneAgent
-        run: bash tests/macos_cleanroom_test.sh
-
-      - name: Smoke packaged executable on Windows
-        if: runner.os == 'Windows'
-        shell: pwsh
-        run: |
-          $homeDir = Join-Path $env:RUNNER_TEMP "oneagent-package-home"
-          ./build/pyinstaller-dist/OneAgent/OneAgent.exe --agent openclaw --check-agent-only --json --home $homeDir
-
-      - name: Install and verify all locked Agents
-        run: python scripts/verify_locked_agents.py
-
-      # verify_locked_agents resolves commands through an injected which() over a
-      # PATH it built itself, so it proves OneAgent believes the install worked.
-      # This proves the shell agrees: npm's global prefix differs per machine and
-      # a binary that never lands on PATH is the common real-world failure.
-      - name: Verify a blank machine can run Codex and Claude Code
-        if: runner.os != 'Windows'
-        shell: bash
-        run: bash tests/real_install_test.sh
-
-      # A configured Agent can still fail to adopt what we wrote -- the Claude
-      # Code "Not logged in" defect, found outside the real-key threshold. This
-      # points the config at the discard port with no key and asserts the failure
-      # is at the network layer (config adopted), not the auth layer (ignored).
-      # It installs the Agents itself, so it needs no secret and no prior step's
-      # prefix.
-      - name: Verify configured Agents adopt their config without a key
-        if: runner.os != 'Windows'
-        run: python scripts/agent_config_adopted_check.py
-
-      - name: Upload blank-machine verification failures
-        if: failure() && runner.os != 'Windows'
-        uses: actions/upload-artifact@v4
-        with:
-          name: real-install-${{ matrix.os }}
-          path: build/real-install
-          if-no-files-found: ignore
-
-      - name: Validate release contents
-        run: python scripts/check_release.py release
-
-      - name: Upload macOS cleanroom failures
-        if: failure() && runner.os == 'macOS'
-        uses: actions/upload-artifact@v4
-        with:
-          name: macos-cleanroom-failures-${{ matrix.os }}
-          path: build/macos-cleanroom
-          if-no-files-found: ignore
-
-      - uses: actions/upload-artifact@v4
-        with:
-          name: OneAgent-${{ matrix.os }}-release-candidate-unsigned
-          path: release/*
-          if-no-files-found: error
-
-  provider-protocol-smoke:
-    name: PPIO and Novita protocol smoke
-    needs: native-build-and-agent-install
-    runs-on: ubuntu-22.04
-    env:
-      ONEAGENT_PPIO_API_KEY: ${{ secrets.ONEAGENT_PPIO_API_KEY }}
-      ONEAGENT_PPIO_OPENAI_MODEL: ${{ vars.ONEAGENT_PPIO_OPENAI_MODEL }}
-      ONEAGENT_PPIO_ANTHROPIC_MODEL: ${{ vars.ONEAGENT_PPIO_ANTHROPIC_MODEL }}
-      ONEAGENT_PPIO_RESPONSES_MODEL: ${{ vars.ONEAGENT_PPIO_RESPONSES_MODEL }}
-      ONEAGENT_NOVITA_API_KEY: ${{ secrets.ONEAGENT_NOVITA_API_KEY }}
-      ONEAGENT_NOVITA_OPENAI_MODEL: ${{ vars.ONEAGENT_NOVITA_OPENAI_MODEL }}
-      ONEAGENT_NOVITA_ANTHROPIC_MODEL: ${{ vars.ONEAGENT_NOVITA_ANTHROPIC_MODEL }}
-      ONEAGENT_NOVITA_RESPONSES_MODEL: ${{ vars.ONEAGENT_NOVITA_RESPONSES_MODEL }}
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Run low-token protocol checks
-        run: python scripts/provider_rc_smoke.py --provider all --timeout 30
diff --git a/.github/workflows/technical-preview.yml b/.github/workflows/technical-preview.yml
deleted file mode 100644
index f4e0f9ee..00000000
--- a/.github/workflows/technical-preview.yml
+++ /dev/null
@@ -1,263 +0,0 @@
-name: Technical Preview Packages
-
-on:
-  workflow_dispatch:
-    inputs:
-      release_tag:
-        description: Draft release tag
-        required: true
-        default: v0.2.0-dev-preview.1
-        type: string
-      create_draft_release:
-        description: Create an immutable draft GitHub prerelease
-        required: true
-        default: true
-        type: boolean
-      deploy_pages:
-        description: Deploy after the draft release has been reviewed and published
-        required: true
-        default: false
-        type: boolean
-  push:
-    tags:
-      - "v*-preview*"
-
-permissions:
-  contents: write
-  pages: write
-  id-token: write
-
-concurrency:
-  group: technical-preview-${{ github.ref }}
-  cancel-in-progress: false
-
-jobs:
-  build:
-    name: ${{ matrix.label }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-22.04
-            label: Linux x64
-            source: "--source"
-          - os: windows-2022
-            label: Windows x64
-            source: ""
-          - os: macos-15
-            label: macOS arm64
-            source: ""
-          - os: macos-15-intel
-            label: macOS x64
-            source: ""
-    runs-on: ${{ matrix.os }}
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "22"
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
-
-      - name: Install build dependencies
-        run: python -m pip install pyinstaller==6.21.0
-
-      - name: Install and build frontend
-        working-directory: frontend
-        run: |
-          npm ci
-          npm run build
-
-      - name: Build unsigned onedir package
-        shell: bash
-        run: python scripts/build_release.py --channel technical-preview-unsigned --skip-frontend ${{ matrix.source }}
-
-      - name: Smoke packaged CLI on Unix
-        if: runner.os != 'Windows'
-        shell: bash
-        run: |
-          home_dir="$(mktemp -d)"
-          build/pyinstaller-dist/OneAgent/OneAgent --agent openclaw --check-agent-only --json --home "$home_dir"
-
-      - name: Smoke packaged CLI on Windows
-        if: runner.os == 'Windows'
-        shell: pwsh
-        run: |
-          $homeDir = Join-Path $env:RUNNER_TEMP "oneagent-package-home"
-          ./build/pyinstaller-dist/OneAgent/OneAgent.exe --agent openclaw --check-agent-only --json --home $homeDir
-
-      - name: Real macOS arm64 cleanroom
-        if: matrix.os == 'macos-15'
-        env:
-          ONEAGENT_PACKAGED_BINARY: ${{ github.workspace }}/build/pyinstaller-dist/OneAgent/OneAgent
-        run: bash tests/macos_cleanroom_test.sh
-
-      - name: Validate release contents
-        run: python scripts/check_release.py release
-
-      - name: Upload native release files
-        uses: actions/upload-artifact@v4
-        with:
-          name: OneAgent-${{ matrix.os }}-technical-preview-unsigned
-          path: release/*
-          if-no-files-found: error
-
-      - name: Upload cleanroom evidence
-        if: always() && matrix.os == 'macos-15'
-        uses: actions/upload-artifact@v4
-        with:
-          name: macos-arm64-cleanroom-evidence
-          path: build/macos-cleanroom
-          if-no-files-found: ignore
-
-  assemble:
-    name: Assemble release and public site
-    needs: build
-    runs-on: ubuntu-22.04
-    outputs:
-      page_artifact_uploaded: ${{ steps.page_condition.outputs.uploaded }}
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Download all native release files
-        uses: actions/download-artifact@v4
-        with:
-          pattern: OneAgent-*-technical-preview-unsigned
-          path: build/native-release
-          merge-multiple: true
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "22"
-          cache: npm
-          cache-dependency-path: site/package-lock.json
-
-      - name: Configure GitHub Pages metadata
-        if: github.event_name == 'workflow_dispatch' && inputs.deploy_pages
-        id: pages
-        uses: actions/configure-pages@v5
-
-      - name: Select immutable release bytes
-        env:
-          GH_TOKEN: ${{ github.token }}
-          RELEASE_TAG: ${{ github.event_name == 'push' && github.ref_name || inputs.release_tag }}
-          DEPLOY_PAGES: ${{ github.event_name == 'workflow_dispatch' && inputs.deploy_pages || false }}
-        shell: bash
-        run: |
-          rm -rf release
-          mkdir -p release
-          if [[ "$DEPLOY_PAGES" == "true" ]]; then
-            release_state="$(gh release view "$RELEASE_TAG" --json isDraft,isPrerelease --jq '[.isDraft, .isPrerelease] | @tsv')"
-            if [[ "$release_state" != $'false\ttrue' ]]; then
-              echo "Release $RELEASE_TAG must be a published prerelease before the website is deployed." >&2
-              exit 1
-            fi
-            gh release download "$RELEASE_TAG" --dir release
-            rm -f release/release-index.json
-          else
-            cp build/native-release/* release/
-          fi
-
-      - name: Install and test public site
-        working-directory: site
-        run: |
-          npm ci
-          npm test
-
-      - name: Install Chromium for public site checks
-        working-directory: site
-        run: npx playwright install --with-deps chromium
-
-      - name: Run public site browser and accessibility checks
-        working-directory: site
-        run: npm run test:e2e
-
-      - name: Build verified public site
-        working-directory: site
-        env:
-          SITE_URL: ${{ steps.pages.outputs.origin || 'http://localhost:4321' }}
-          BASE_PATH: ${{ steps.pages.outputs.base_path || '/' }}
-          PUBLIC_SUPPORT_URL: ${{ vars.ONEAGENT_PUBLIC_SUPPORT_URL }}
-          PUBLIC_BUSINESS_EMAIL: ${{ vars.ONEAGENT_PUBLIC_BUSINESS_EMAIL }}
-        run: npm run build
-
-      - name: Prepare public release assets
-        run: |
-          python scripts/build_release_index.py \
-            --release-dir release \
-            --channels distribution/channels.json \
-            --output build/release-index.json \
-            --copy-release-assets build/public-release
-
-      - name: Create immutable draft prerelease
-        if: github.event_name == 'push' || inputs.create_draft_release
-        env:
-          GH_TOKEN: ${{ github.token }}
-          RELEASE_TAG: ${{ github.event_name == 'push' && github.ref_name || inputs.release_tag }}
-        run: |
-          if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
-            mkdir -p build/existing-release
-            gh release download "$RELEASE_TAG" --dir build/existing-release
-            python - <<'PY'
-          import hashlib
-          import os
-          from pathlib import Path
-
-          expected = Path("build/public-release")
-          existing = Path("build/existing-release")
-          expected_files = {path.name: hashlib.sha256(path.read_bytes()).hexdigest() for path in expected.iterdir() if path.is_file()}
-          existing_files = {path.name: hashlib.sha256(path.read_bytes()).hexdigest() for path in existing.iterdir() if path.is_file()}
-          if expected_files != existing_files:
-              raise SystemExit(
-                  f"Release {os.environ['RELEASE_TAG']} already exists with different assets; bump the version/tag instead of replacing bytes."
-              )
-          print(f"Release {os.environ['RELEASE_TAG']} already contains the exact verified assets; nothing was replaced.")
-          PY
-          else
-            gh release create "$RELEASE_TAG" build/public-release/* \
-              --draft \
-              --prerelease \
-              --target "$GITHUB_SHA" \
-              --title "OneAgent $RELEASE_TAG" \
-              --notes "Unsigned technical preview. Verify platform, architecture and SHA-256 before use."
-          fi
-
-      - name: Mark Pages artifact condition
-        id: page_condition
-        shell: bash
-        run: |
-          if [[ "${{ github.event_name }}" == "workflow_dispatch" && "${{ inputs.deploy_pages }}" == "true" ]]; then
-            echo "uploaded=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "uploaded=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Upload GitHub Pages artifact
-        if: steps.page_condition.outputs.uploaded == 'true'
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: site/dist
-
-  deploy-pages:
-    name: Deploy verified public site
-    needs: assemble
-    if: needs.assemble.outputs.page_artifact_uploaded == 'true'
-    runs-on: ubuntu-22.04
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index 90350cc5..a95f913d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,14 +1,17 @@
 .DS_Store
-__pycache__/
-*.py[cod]
-.coverage
-.venv/
-htmlcov/
-build/
-dist/
+# Anchored to the repository root. Written as a bare `dist/` it matched at any
+# depth, and because excluding a directory stops git from descending into it, the
+# `!frontend/dist/.keep` exception two lines down could never take effect — so
+# the .keep that manifest_embed.go's `go:embed all:frontend/dist` needs was
+# silently absent from every clone.
+/dist/
 release/
+# oneagent-release 的中间产物：notice、license 副本和打包暂存目录
+build/metadata/
+build/release-stage/
 frontend/node_modules/
-frontend/dist/
+frontend/dist/*
+!frontend/dist/.keep
 frontend/coverage/
 frontend/test-results/
 frontend/playwright-report/
@@ -17,9 +20,9 @@ frontend/playwright-report/
 output/
 .qoder/
 
-# 构建 wheel 时由 setup.py 暂存的运行时资源
-oneagent/_resources/
-*.egg-info/
+# Go CLI 与桌面壳的本地构建产物；scripts/install.* 只转发，不构建。
+bin/
+
 # 公开站点：构建缓存与测试产物
 site/node_modules/
 site/dist/
@@ -28,8 +31,4 @@ site/coverage/
 site/test-results/
 site/playwright-report/
 
-# 站点数据由 `npm run prepare:data` 从 agents.lock.json、distribution/ 与
-# release/ 重新生成。提交它们会让每次构建都产生 diff，而 release-index 还会
-# 把只有本机才有的产物校验和写进仓库。
-site/src/generated/
-site/public/downloads/
+.task
diff --git a/CLAUDE.md b/CLAUDE.md
index fd5f9628..48e6a98a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,92 +1,64 @@
-# CLAUDE.md
+# OneAgent 开发约定
 
-OneAgent：本地 AI 开发环境激活器。Python 3.12 标准库内核 + React 七页向导，经 `127.0.0.1` HTTP 通信，负责检测、安装并配置 5 个 CLI Agent 指向 OpenAI- 或 Anthropic-compatible Provider。
+当前分支是 Go/Wails 收尾线，版本为 `0.3.0-dev`。桌面入口是 `cmd/oneagent-desktop`，headless CLI 是 `cmd/oneagent`；两者共享 `internal/` 用例。React 只通过生成的 Wails bindings 调用后端。
 
-当前 `0.2.0-dev`，发行渠道只能标记 `technical-preview-unsigned`。功能说明与发行流程见 [README.md](README.md)。
+## 目录
 
-## 沟通语言
+- `internal/app`：Status、Provider、Agent、Profile 用例和写入协调锁。
+- `internal/catalog`：嵌入的 `agents.lock.json`、`providers.lock.json`、`runtimes.lock.json` 与内置 Provider 目录。
+- `internal/config`：TOML/JSON/JSONC 适配器、配置发现和 golden fixtures。
+- `internal/install`：锁定包安装、registry/integrity 校验、Node.js/uv 运行时引导（下载、校验、解压、写入 PATH）和 Aider 外部前置条件。
+- `internal/profile`、`internal/securefs`：profile、secret、备份、权限和原子写。
+- `cmd/oneagent`
+- `cmd/oneagent-release`：原生 Wails/Go/React 发布包、notice、manifest 和 SHA-256。
+- `cmd/oneagent-rc`、`cmd/oneagent-provider-smoke`：发行候选的真实 Agent/Provider 检查。
+- `frontend/bindings`：Wails 生成物，禁止手工编辑。
+- `site`：独立 Astro 公开站。
 
-**回复一律使用简体中文，没有例外。** 包括分析、结论、计划、代码审查意见和确认提问；用户用英文提问也不切换。代码、标识符、提交信息和代码注释保持英文（与现有代码库一致）；README、`docs/` 和 ADR 保持中文。
+`providers.lock.json` 是内置 Provider 端点、fallback model 和公开站商业披露字段的真源；用户 Provider 与内置覆盖保存在 `~/.oneagent/providers.json`。
 
-## 常用命令
-
-本机 `python3` 是 3.14，测试与打包必须显式用 `python3.12`；`scripts/gui.py` 用任意 ≥3.12 均可。
+## 本地命令
 
 ```bash
-# Python 契约测试（74 用例，约 7s）
-python3.12 -m unittest tests.test_core tests.test_cli tests.test_server \
-  tests.test_release_policy tests.test_edge_cases tests.test_rc_scripts
-
-# 覆盖率门禁：整体 ≥85%，installer.py 必须 100% 分支且无 partial
-python3.12 -m coverage run --branch -m unittest tests.test_core tests.test_cli \
-  tests.test_server tests.test_release_policy tests.test_edge_cases tests.test_rc_scripts
-python3.12 -m coverage report --fail-under=85
-
-# 源码 GUI
-python3 scripts/gui.py --port 8765 --no-open
-
-# 前端（build 会先跑 tsc --noEmit）
-cd frontend && npm ci && npm run build
-npm run test:coverage
-npm run e2e                            # Playwright 自动拉起 gui.py:8765
-
-# 隔离验证
-bash tests/install_test.sh             # install.sh 端到端，临时 HOME
-python3.12 tests/gui_smoke_test.py     # 真实 HTTP + Cookie/Origin 冒烟
-bash scripts/test_docker_cleanroom.sh  # Linux 断网 cleanroom
+go test ./...
+go test -race ./...
+go vet ./...
+go build -o bin/oneagent ./cmd/oneagent
+
+cd frontend
+npm ci
+npm run test
+npm run build
+npm run test:e2e
 ```
 
-## 代码地图
+构建和检查发行包：
 
+```bash
+go run ./cmd/oneagent-release build --channel technical-preview-unsigned --source
+go run ./cmd/oneagent-release check release
 ```
-oneagent/          Python 内核，零第三方依赖
-  catalog.py       读 agents.lock.json、平台/HOME 解析、PROVIDERS 常量
-  providers.py     base URL 校验与推导、chat_probe、list_models
-  installer.py     主体：原子写、备份、权限、5 个配置适配器、install_many、status_payload
-  server.py        stdlib http.server：/api/{status,probe,models,install,profiles,open-register}、
-                   POST /api/agents/<id>/activate（单 Agent 重新指向）+ 静态托管
-  cli.py           argparse CLI          errors.py  OneAgentError + 错误码→退出码
-  entrypoint.py    打包版入口：无参→GUI，有参→CLI
-frontend/src/
-  App.tsx          react-router 七页 + SetupGuard 前置校验
-  state/           useReducer + Context，WizardState 是唯一状态源
-  api/client.ts    fetch 封装，非 2xx 抛 OneAgentApiError
-agents.lock.json   Agent 版本/包管理器/配置适配器/平台/许可证的唯一真源
-scripts/           gui.py、install.sh/.ps1、build_release.py、check_release.py
-```
-
-主链路：`React → POST /api/install → install_many() → _write_agent_config() → atomic_write()`。
-
-## 硬性约束
 
-改动前先确认不会破坏以下条目，`tests/test_release_policy.py` 与 CI 会直接拦截：
+真实 RC 只在受控环境运行：
 
-- **零运行时依赖**：`oneagent/` 只用标准库，`pyproject.toml` 的 `dependencies` 保持为空。
-- **禁止 `shell=True` 与 `curl | sh`**：子进程一律走 `runtime.runner([...])` 列表参数。
-- **只绑定 127.0.0.1**：`create_server` 拒绝其他 host；POST 同时校验 Origin 白名单与 HttpOnly/SameSite=Strict 会话 Cookie（`secrets.compare_digest`）。
-- **API Key 不落地**：不进 `profile.json`、argv、URL、日志、React state、浏览器存储；日志一律过 `redact(text, [api_key])`。
-- **写配置只走 `atomic_write`**：`ensure_private_dir`(0700) → 备份 `*.backup-<ts>` → 临时文件先 `secure_path`(0600 / Windows icacls 断继承) → `os.replace`。密钥备份无法加固时删除并报错。
-- **保留用户字段**：Codex TOML 与 Claude/OpenCode/Kilo JSON 合并时不得丢弃非 OneAgent 管理的键；解析失败返回 `CONFIG_WRITE_FAILED`，绝不静默覆盖。
-- **版本锁定**：`agents.lock.json` 不允许 `latest`，npm 包必须带 `sha512-` integrity；`--latest` 仅在用户显式指定时生效。
-- **guide-only Agent** 不装包、不写私有配置、不起后台服务。
-- **前端产物**不得包含 source map 或 CDN/远程字体引用。
-- **覆盖率**：`oneagent/installer.py` 100% 分支且 `num_partial_branches == 0`；Python 整体与前端 `src/api`、`src/state` 均 ≥85%。
-- 产品边界（禁 VPN/代理/共享 Key/自动登录）见 [docs/product-boundary-baseline.md](docs/product-boundary-baseline.md)，突破需新增 ADR。
-
-## 代码约定
-
-- Python 文件均以 `from __future__ import annotations` 开头，全量类型注解，dataclass 承载配置。
-- **副作用全部经 `Runtime`**：`home / os_id / runner / which / env` 都是可注入字段，测试靠替换它们模拟 npm、uv 与四个平台，不触碰真实系统。新增代码不要直接调用 `subprocess.run`、`shutil.which`、`os.environ` 或 `Path.home()`。
-- 失败一律 `raise OneAgentError(code, message)`，code 取自 `errors.EXIT_CODES`；响应恒定携带 `error / message / status / error_code / retryable`。
-- 传输契约：请求体 snake_case，`StatusResponse` 等派生字段 camelCase——改一侧必须同步 `frontend/src/types/api.ts`。
-- 常规 CI 使用假的 npm/uv，不下载真实 Agent、不访问 Provider；真实安装与 Provider 冒烟只在手动 `release-candidate.yml` 执行。
+```bash
+go run ./cmd/oneagent-rc verify-agents
+go run ./cmd/oneagent-rc adopted
+go run ./cmd/oneagent-provider-smoke --provider all --timeout 30s
+```
 
-## 常见任务
+普通测试、Wails 构建、站点构建和发布工具不需要 Python。安装 Aider 需要 Python 3.12，但不再要求本机预装：uv 自己解析解释器，本机有匹配版本就复用，否则下载一份托管 CPython 到 `~/.oneagent/runtimes/python`。Python 仍然不进发行包。
 
-**新增自动配置 Agent**：`agents.lock.json` 补条目（`command` / `config_path` / `config_adapter` / `credential_delivery` 必填，version/integrity/source/license/platforms 同旧）→ 在 `installer.py` 写 `write_*_config` 并注册到 `_write_agent_config` 分派 → 更新 `tests/test_core.py` 的适配器断言。
+## 代码边界
 
-`credential_delivery` 决定密钥怎么到达 Agent，取值 `oneagent_env`（配置文件引用 `ONEAGENT_*` 变量）、`native_env`（Agent 只读自己的变量名，需同时给 `env_vars`）、`config_file`（密钥在适配器写的配置里）。**启动命令、重启提示和 env 文件都由此推导，不要在 Python 里按 agent id 特判**——Claude Code 曾因为不在硬编码集合里而报「配置完成」却无法认证。
+- `agents.lock.json` 是 Agent 元数据唯一真源。新增自动配置 Agent 时先补 lock，再添加对应 config adapter 和 Go 测试。
+- 子进程必须使用 argv 数组和受控环境，设置超时并保留可诊断但已脱敏的输出。
+- 写入顺序必须是私有目录、备份、同目录临时文件、收紧权限、原子替换；密钥备份无法收紧时删除并失败。
+- 不把 API Key 写入普通 profile、状态摘要、日志、URL、全局 React state、浏览器存储或测试附件；仅 Provider 编辑/配置表单可通过本机 binding 按需读取私有存储中的 Key。
+- Provider 按 Agent 协议探测；`/v1/models` 不能替代 Responses、Anthropic Messages 或 Chat Completions 检查。
+- Wails 生产构建不能使用 `server` tag；浏览器 E2E 才能使用 server/e2e fake runner。
+- Linux 发行构建固定使用 `gtk3` tag，Wails Alpha 阶段只允许 `technical-preview-unsigned`。
 
-**新增 Provider**：`catalog.py` 的 `PROVIDERS` 加 `base_url` 与 `anthropic_base_url` → 同步 `frontend/src/types/api.ts` 的 `ProviderId`。
+## 文档维护
 
-**改错误码**：`errors.EXIT_CODES` 与 README「错误契约」小节必须同时更新。
+README、workflow、Taskfile、Dockerfile 和 AI Agent Kit 里的命令必须对应当前仓库文件。历史 ADR 可以保留背景，但必须明确标记为 Superseded，不能作为操作指南。
diff --git a/Dockerfile.test b/Dockerfile.test
deleted file mode 100644
index e9b0174f..00000000
--- a/Dockerfile.test
+++ /dev/null
@@ -1,39 +0,0 @@
-FROM mcr.microsoft.com/playwright:v1.61.1-noble@sha256:5b8f294aff9041b7191c34a4bab3ac270157a28774d4b0660e9743297b697e48
-
-USER root
-
-ENV DEBIAN_FRONTEND=noninteractive \
-    PLAYWRIGHT_BROWSERS_PATH=/ms-playwright \
-    PATH=/opt/oneagent-venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-
-RUN set -eux; \
-    sed -i 's|http://|https://|g' /etc/apt/sources.list.d/ubuntu.sources; \
-    for attempt in 1 2 3 4 5; do \
-        if apt-get -o Acquire::Retries=3 update; then break; fi; \
-        if [ "$attempt" = "5" ]; then exit 1; fi; \
-        rm -rf /var/lib/apt/lists/*; \
-        sleep "$((attempt * 5))"; \
-    done; \
-    apt-get install -y --no-install-recommends \
-        python3.12 \
-        python3.12-venv \
-        ripgrep; \
-    rm -rf /var/lib/apt/lists/*; \
-    python3.12 -m venv /opt/oneagent-venv; \
-    /opt/oneagent-venv/bin/python -m pip install --no-cache-dir coverage==7.15.2
-
-WORKDIR /opt/oneagent
-
-COPY --chown=pwuser:pwuser frontend/package.json frontend/package-lock.json ./frontend/
-
-USER pwuser
-RUN cd frontend && npm ci
-
-USER root
-COPY --chown=pwuser:pwuser . .
-RUN chown pwuser:pwuser /opt/oneagent \
-    && chmod +x scripts/install.sh scripts/test_docker_cleanroom.sh scripts/run_container_cleanroom.sh tests/install_test.sh
-
-USER pwuser
-
-ENTRYPOINT ["bash", "scripts/run_container_cleanroom.sh"]
diff --git a/README.md b/README.md
index 9e5d3528..1fb72257 100644
--- a/README.md
+++ b/README.md
@@ -1,223 +1,89 @@
 # OneAgent
 
-OneAgent 是一个本地 AI 开发环境激活器。它用 React 七页向导检测、安装并初始化常用 Agent，同时保留 Bash、PowerShell 和结构化 CLI。安装、备份、权限、Provider 探测和配置写入统一由 Python 3.12 核心完成。
+OneAgent 是一个本地 AI 开发环境激活器。React 向导和纯 Go CLI 共用同一套 Go 用例，负责检测 Agent、安装锁定版本、探测 Provider、合并配置、创建备份并收紧权限。桌面应用使用 Wails v3 binding；生产进程不监听业务 TCP 端口。
 
-OneAgent 不重新分发 Agent 二进制，不捆绑 Node.js、Python、Git Bash、VPN、代理、共享 API Key 或第三方配置工具。缺少前置工具时只返回明确错误和官方安装指引。
+OneAgent 不重新分发 Agent 包，也不捆绑 Node.js、系统 WebView、Git 或 API Key。缺少运行前置条件时返回明确错误和官方安装指引。
 
 ## 当前状态
 
-当前版本为 `0.2.0-dev`，当前发行目标是可直接下载运行的 `technical-preview-unsigned` 二进制包。不以四平台同时分发作为产品阶段门槛；每个实际发布的平台仍须在对应操作系统原生构建，并以 CI cleanroom 作业作为验收证据。各平台最低目标见 [ADR-003](docs/decisions/ADR-003-three-platform-python-core-and-release-policy.md)。
-
-发行渠道不限定为 GitHub。官网、GitHub Release、网盘和企业云盘可以作为同一官方构建的镜像，但同一版本必须保持文件内容和 SHA-256 一致，渠道方不得重新打包或加入渠道专属内容。每个产物只声明实际构建和验证过的目标环境。
-
-仍未取得证据的部分：
-
-- **真实 Agent 安装与真实 Provider 冒烟**：只在手动 `release-candidate.yml` 执行，需要受保护的 `ONEAGENT_PPIO_API_KEY`、`ONEAGENT_NOVITA_API_KEY` 与六个协议模型变量，尚未配置，因此尚未运行。
-- **Codex 的 Responses 协议**：PPIO/Novita 的 `/v1/responses` 仍未用真实 Key 验收；仅验证 Chat Completions 不能证明 Codex 可用。
-
-当前阶段不处理平台商店、自动更新、macOS 公证或 Windows Authenticode，因此不使用 Stable 标签。Stable 门槛（macOS 签名/公证、Windows Authenticode）仍然有效并由 `scripts/build_release.py` 做产物级强制，当前只是不发布 Stable。完整包体、品牌、许可证、Key、渠道台账和跨渠道撤回规则见 [多渠道分发与合规政策](docs/distribution-compliance-policy.md)。
+当前版本为 `0.3.0-dev`，Wails 仍处于 Alpha，因此发布渠道只能是 `technical-preview-unsigned`。Python 迁移已经完成：受版本控制的旧实现、测试、PyInstaller/wheel 打包链路均已删除；普通构建、测试、运行和发布只需要 Go、Node（构建前端）及目标平台 WebView。Aider 是唯一例外：只有用户选择安装 Aider 时，才要求本机已有 Python 3.12，OneAgent 不会下载或管理它。
 
 ## 架构
 
 ```text
 React + TypeScript + Vite
           |
-          | localhost JSON API
+          | generated Wails bindings
           v
-Python 3.12 HTTP Server
+Status / Provider / Agent / Profile services
           |
           v
-oneagent.installer
-  - 平台路径和前置检测
-  - 锁定版本安装
-  - 配置合并和备份
-  - Unix mode / Windows ACL
-  - Provider 探测和结构化错误
-```
-
-- `scripts/gui.py`：源码 GUI 入口。
-- `scripts/install.sh`：macOS/Linux CLI 转发层。
-- `scripts/install.ps1`：Windows CLI 转发层。
-- `oneagent/`：三平台共用安装核心、API Server 和 CLI。
-- `frontend/`：React 七页向导；发行包只携带构建后的 `dist`，终端用户不需要 Node.js。
-- `site/`：独立 Astro 静态公开站；不进入 Launcher 包体，也不复用本地路由和状态。
-- `distribution/`：公开渠道状态与 Provider 商业关系披露；技术排序与商业数据保持分离。
-- `agents.lock.json`：五个自动配置 Agent 的版本、包管理器、配置适配器、平台、来源和许可证锁定清单。
-
-## 公开分发站
-
-公开站从平台 manifest、SHA256SUMS、`agents.lock.json` 和 `distribution/` 配置生成下载与兼容目录，不手工复制版本或哈希：
+      Go application use cases
+          |
+  catalog / provider / install / config / profile / securefs
 
-```bash
-cd site
-npm ci
-npm test
-npm run build
-npx playwright install chromium
-npm run test:e2e
+Pure Go CLI --------------------^      Astro site ---- release metadata
 ```
 
-`npm run build` 会生成 `/release-index.json` 并校验公开 artifact 的大小与 SHA-256。`site/src/generated/` 与 `site/public/downloads/` 都由构建重新生成，不提交到 Git。GitHub Pages 子路径构建可设置 `SITE_URL` 与 `BASE_PATH`（该产物无法本地预览，原因见运营手册）。完整发布、镜像、Provider 披露和撤回流程见 [公开分发站运营与发布手册](docs/public-site-operations.md)。
+- `cmd/oneagent-desktop`：Wails 桌面入口。
+- `cmd/oneagent`：纯 Go headless CLI。
+- `cmd/oneagent-release`：构建、notice、manifest、SHA-256 和发行包检查。
+- `cmd/oneagent-rc`：真实锁定 Agent 安装和无密钥配置采用检查。
+- `cmd/oneagent-provider-smoke`：PPIO/Novita 三协议 RC smoke。
+- `internal/`：桌面、CLI 和 RC 工具共用的 Go 核心。
+- `frontend/`：React 应用；发行包只携带构建后的静态资源。
+- `site/`：独立 Astro 公开站，不进入桌面包体。
+- `agents.lock.json`：Agent 版本、来源、配置适配器和许可证的唯一清单。
+- `providers.lock.json`：内置 Provider 端点、fallback probe model 和公开站披露字段清单；桌面端用户 Provider 保存在本机 `~/.oneagent/providers.json`。
 
 ## 快速启动
 
-### 源码 GUI
-
-源码运行要求 Python 3.12+。如需让 OneAgent 自动安装 Aider，还需要预先安装 `uv`；OneAgent 不会自动下载 Python：
-
-```bash
-python3 scripts/gui.py
-```
-
-固定端口且不自动打开浏览器：
-
-```bash
-python3 scripts/gui.py --port 8765 --no-open
-```
-
-GUI 只监听 `127.0.0.1`。首页设置随机 HttpOnly、SameSite=Strict 会话 Cookie，所有 POST 同时校验 Cookie 和 localhost Origin。
-
-### 打包版
-
-解压对应平台的 onedir 压缩包后运行：
+### 桌面应用
 
 ```bash
-./OneAgent/OneAgent
-```
-
-Windows：
-
-```powershell
-.\OneAgent\OneAgent.exe
-```
-
-未签名预览版不是 Stable。OneAgent 不提供绕过操作系统安全策略的指令。
-
-### Python 包安装
-
-OneAgent 内核只依赖标准库，可以直接作为 Python 包安装。已有 Python 3.12+ 的用户走这条路**不涉及 onedir 压缩包**，因此不触发 macOS Gatekeeper 或 Windows SmartScreen 对下载可执行文件的拦截：
-
-```bash
-uv tool install ./OneAgent-0.2.0.dev0-py3-none-any.whl
-# 或 pipx install ./OneAgent-0.2.0.dev0-py3-none-any.whl
-```
-
-安装后提供两个入口：
-
-```bash
-oneagent --agent codex --check-agent-only   # CLI
-oneagent-gui --port 8765 --no-open          # 本地 GUI
-```
-
-wheel 会把 `agents.lock.json` 与构建后的 `frontend/dist` 一并打进包内（见 `setup.py`），因此安装后无需仓库即可运行。本地构建 wheel：
-
-```bash
-python3.12 -m pip wheel . --no-deps -w dist
+cd frontend
+npm ci
+npm run build
+cd ..
+go run -tags wails ./cmd/oneagent-desktop
 ```
 
-尚未发布到 PyPI，目前只能从本地或 Release 附件安装。
+生产构建需要目标平台的 Wails/WebView 依赖。Linux 当前使用 `gtk3` tag（Ubuntu 22.04 cleanroom）；macOS 使用系统 WKWebView；Windows 使用 WebView2 Runtime。
 
 ### CLI
 
-macOS/Linux：
-
 ```bash
-ONEAGENT_API_KEY="$MY_API_KEY" \
-./scripts/install.sh \
-  --agent codex \
-  --provider ppio \
-  --model your-model-id \
-  --channel direct
+go build -o bin/oneagent ./cmd/oneagent
 ```
 
 Windows PowerShell：
 
 ```powershell
+go build -o bin\\oneagent.exe .\\cmd\\oneagent
 $env:ONEAGENT_API_KEY = $MyApiKey
-.\scripts\install.ps1 --agent codex --provider ppio --model your-model-id
+.\\scripts\\install.ps1 --agent codex --provider ppio --model your-model-id
 ```
 
-`--api-key` 仅为旧参数兼容和受控测试保留。日常使用应通过 GUI、交互粘贴或 `ONEAGENT_API_KEY` 传入，避免进入 shell history。
+日常使用优先通过 `ONEAGENT_API_KEY`、桌面粘贴或已保存 profile 传递凭据；`--api-key` 仅保留给受控脚本。 `--registry` 默认是官方 npm registry，镜像必须显式选择并使用 HTTPS。
 
-只检测或安装 Agent、不写模型配置：
+### 公开站
 
 ```bash
-./scripts/install.sh --agent codex --check-agent-only
-```
-
-显式安装锁定版本：
-
-```bash
-./scripts/install.sh --agent codex --check-agent-only --install-agent --locked-version
-```
-
-`--latest` 只能由用户显式选择，默认安装与发布测试均使用 `agents.lock.json` 的锁定版本。安装前会用 `npm view` 取 registry 声明的 `dist.integrity` 与锁定清单比对，不一致或版本不存在时拒绝安装，不会退到其他版本。
-
-官方 npm registry 不可达时可显式指定授权镜像：
-
-```bash
-./scripts/install.sh --agent codex --install-agent --locked-version --registry npmmirror
-```
-
-`--registry` 接受镜像 id（`official`、`npmmirror`）或 `https://` URL，只允许 HTTPS 且不得携带凭据。**默认始终是官方源**，镜像永远是显式选择，不会因网络失败自动切换——否则用户无法得知包的来源。实际使用的 registry 会记入安装日志。镜像只能是第三方公开 registry，OneAgent 不托管、不重打包任何 Agent 包体。
-
-## GUI 流程
-
-1. 多选 Agent，并查看本机安装、配置和前置条件状态。
-2. 选择配置模型服务，或使用官方账号/已有本地配置。
-3. 选择 PPIO、Novita 或 Custom，填写 Key 并测试连接。
-4. 请求 `GET <openai-base>/v1/models`；失败时手动输入模型 ID。
-5. 确认 Agent、写入路径、备份策略和 guide-only 项目。
-6. 同步执行安装与配置，按 Agent 返回最终状态；不伪造百分比。
-7. 从不含 Key 的 `~/.oneagent/profile.json` 恢复环境总览。
-
-## Provider
-
-| Provider | 官网 | OpenAI-compatible base | Anthropic-compatible base |
-| --- | --- | --- | --- |
-| PPIO | `https://ppio.com/` | `https://api.ppio.com/openai` | `https://api.ppio.com/anthropic` |
-| Novita | `https://novita.ai/` | `https://api.novita.ai/openai` | `https://api.novita.ai/anthropic` |
-
-连接测试使用：
-
-```text
-POST <openai-base>/v1/chat/completions
-GET  <openai-base>/v1/models
+cd site
+npm ci
+npm test
+npm run build
+npx playwright install chromium
+npm run test:e2e
 ```
 
-Custom 支持 HTTP/HTTPS，包括用户主动配置的本机地址；拒绝 URL 凭据、非法 scheme 和控制字符。推荐显式使用 `--provider custom --api-base-url ...`。为兼容旧 CLI，合法 Provider 也可以用 `--api-base-url` 做显式覆盖。
-
-### 按 Agent 协议验证
-
-每个 Agent 配置后实际使用的推理协议不同，OneAgent 按此逐一验证，而不是统一探测 Chat Completions：
-
-| Agent | 协议 | 验证请求 |
-| --- | --- | --- |
-| Codex | Responses | `POST <base>/v1/responses` |
-| Claude Code | Anthropic Messages | `POST <anthropic-base>/v1/messages` |
-| OpenCode、Kilo CLI、Aider | OpenAI-compatible | `POST <base>/v1/chat/completions` |
-
-**同一个模型 ID 不一定同时兼容三种协议**，这不是理论风险。对一个 OpenAI-compatible 中转端点的 36 个文本模型实测：
-
-| 协议 | 通过 |
-| --- | --- |
-| Chat Completions | 31 / 36 |
-| Anthropic Messages | 23 / 36 |
-| **Responses** | **10 / 36** |
-
-在 30 个能明确判定的模型里只有 10 个支持 Responses，判定依据是端点显式回复 `400 "does not support endpoint: responses"` 或 `500 "not implemented"`。因此：
+站点只读取 GitHub Release、`agents.lock.json` 和 `providers.lock.json`，不读取本地 `release/`，也不依赖桌面构建环境。
 
-- 连接测试会带上所选 Agent，逐个协议验证；只验证 Chat Completions 不能证明 Codex 可用。
-- 探测到协议不兼容时返回 `PROTOCOL_UNSUPPORTED` 并**拒绝写入配置**，不会把失败推迟到 Agent 首次请求。
-- 该错误不可重试；配额超限、上游过载等瞬时故障仍按可重试处理。
-- Claude Code 使用 Provider 的 Anthropic-compatible base，并写入 `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL` 和 `ANTHROPIC_SMALL_FAST_MODEL`。
-- 真实 Agent 首次请求仍是发布门禁，不以 `/v1/models` 成功代替。
+## Agent 与 Provider
 
-## Agent 范围
+自动配置 Agent：
 
-### 自动配置
-
-| Agent | 锁定版本 | 安装器 | 配置协议 |
+| Agent | 锁定版本 | 安装器 | 协议 |
 | --- | --- | --- | --- |
 | Codex | `0.145.0` | npm | Responses |
 | Claude Code | `2.1.217` | npm | Anthropic Messages |
@@ -225,214 +91,83 @@ Custom 支持 HTTP/HTTPS，包括用户主动配置的本机地址；拒绝 URL
 | Kilo CLI | `7.4.11` | npm | OpenAI-compatible |
 | Aider | `0.86.2` | uv tool | OpenAI-compatible |
 
-### 只做引导
-
-- 网关型：OpenClaw、Hermes。
-- 官方账号/平台型：Cursor、Kiro、Gemini CLI。
-- IDE 扩展型：Cline、Continue、Qwen Code、Kilo VS Code。
-
-guide-only Agent 不执行包管理器安装，不写私有配置，不启动 daemon、gateway、WSL 或后台服务。
-
-这与许可证无关：OpenClaw 与 Hermes 都是 MIT，分发上没有障碍。真正的原因是形态——两者以常驻网关方式运行，而统一网关被 [ADR-002](docs/decisions/ADR-002-product-boundary-and-network-access.md) 与 [ADR-003](docs/decisions/ADR-003-three-platform-python-core-and-release-policy.md) 明确划在当前范围之外；Cursor 与 Kiro 以应用形式安装并通过自有账号体系登录。
-
-### 界面顺序与可配置性无关
-
-总览按 `agents.lock.json` 的 `rank` 字段排序，依据是该 Agent 的实际使用广度，而不是 OneAgent 能否配置它。因此 Cursor、OpenClaw、Hermes 与 Codex、Claude Code、OpenCode 并列在首屏，Kilo CLI 与 Aider 收进折叠区。guide-only 条目使用同样的行式呈现，只是操作为「官方文档」而非配置表单——把常用工具藏进脚注会让总览无法反映这台机器的真实情况。
-
-Aider 使用隔离的 `uv tool install --python python3.12 --no-python-downloads`，不再调用系统级 pip。缺少 `uv` 或本机 Python 3.12 时返回 `PREREQUISITE_MISSING`，不会绕过 externally-managed Python，也不会自动安装语言运行时。
-
-## 配置与备份
-
-| Agent/状态 | 写入路径 |
-| --- | --- |
-| Codex | `~/.codex/config.toml`、`~/.oneagent/agents/codex.env` |
-| Claude Code | `~/.claude/settings.json`、`~/.oneagent/agents/claude-code.env` |
-| OpenCode | `~/.config/opencode/opencode.jsonc`、`~/.oneagent/agents/opencode.env` |
-| Kilo CLI | `~/.config/kilo/kilo.jsonc`、`~/.oneagent/agents/kilo-cli.env` |
-| Aider | `~/.oneagent/aider.env` 或 Windows `aider.ps1` |
-| 环境摘要 | `~/.oneagent/profile.json` |
+OpenClaw、Hermes、Cursor、Kiro、Gemini CLI、Cline、Continue、Qwen Code 和 Kilo VS Code 仅提供官方安装引导，不安装包、不写私有配置、不启动后台服务。
 
-凭据如何到达各 Agent 由 `agents.lock.json` 的 `credential_delivery` 声明，共三种：
+内置 PPIO、Novita，并支持在 Provider 页面增删改用户 Provider。配置后按 Agent 实际协议探测：Codex 使用 `/v1/responses`，Claude Code 使用 `/v1/messages`，其余自动配置 Agent 使用 `/v1/chat/completions`。协议不兼容时返回 `PROTOCOL_UNSUPPORTED`，不会先写入不可用配置。
 
-- **`oneagent_env`**（Codex、OpenCode、Kilo CLI）——配置文件通过 `env_key` 或 `{env:...}` 引用 `ONEAGENT_API_KEY_CODEX` 这类专属变量，因此三者可同时指向不同 Provider。
-- **`native_env`**（Claude Code）——它只读自己定义的变量名，`env_vars` 声明为 `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL` / `ANTHROPIC_MODEL` / `ANTHROPIC_SMALL_FAST_MODEL`。**只写 `settings.json` 不足以让它认证**——它会忽略其中的凭据并报 `Not logged in`，所以 env 文件同时导出这四个原生变量。
-- **`config_file`**（Aider）——配置本身就是一个导出变量的 shell 脚本，无需额外 env 文件。
-
-因此除 Aider 外，每个 Agent 的启动命令都会先 source 自己的 env 文件；`~/.oneagent/env` 仍写入共享的 `ONEAGENT_API_KEY`，供旧版本写下的配置继续使用。
-
-Codex TOML、Claude/OpenCode/Kilo JSON 会保留非 OneAgent 管理字段。写入前创建 `*.backup-<timestamp>`；损坏配置返回 `CONFIG_WRITE_FAILED`，不会静默覆盖。
-
-API Key 只进入本地密钥配置，不进入 `profile.json`、`agents/<id>.json`、命令行、URL、日志、React reducer、浏览器存储或遥测。Unix 私有目录使用 `0700`、密钥文件和备份使用 `0600`；Windows 关闭 ACL 继承，仅允许当前用户和 SYSTEM。权限设置失败会终止发布写入。
-
-## 按 Agent 管理
-
-每个 Agent 独立记录自己指向的 Provider 与模型，互不影响：绑定写入 `~/.oneagent/agents/<agent-id>.json`（不含 Key），凭据写入同名 `.env`。因此 Codex 可以用 PPIO，同时 OpenCode 用 Novita。
-
-```bash
-oneagent agent list                     # 每个 Agent 当前的 Provider 与模型
-oneagent agent set codex --provider ppio --model deepseek/deepseek-v3 --api-key <KEY>
-oneagent agent set opencode --provider novita --model <MODEL> --profile team
-```
-
-`--profile` 复用 `profiles/` 里已保存模板的 Key，无需重新粘贴。GUI 对应 `POST /api/agents/<id>/activate`。
-
-Agent 在启动时读取配置，因此重新指向后必须重启该 Agent 进程才会生效；响应与 CLI 输出都会给出对应的重启指引。切换只影响单个 Agent，失败不会波及其他 Agent。
-
-## 错误契约
-
-CLI `--json` 和本地 API 使用稳定错误码：
-
-- `INVALID_REQUEST`
-- `INVALID_ORIGIN`
-- `PREREQUISITE_MISSING`
-- `API_KEY_REJECTED`
-- `PROVIDER_UNREACHABLE`
-- `MODELS_UNSUPPORTED`
-- `PROTOCOL_UNSUPPORTED`
-- `AGENT_INSTALL_FAILED`
-- `CONFIG_WRITE_FAILED`
-- `TIMEOUT`
-
-错误响应保留 `error`、`message`、`status`，并提供 `error_code` 和 `retryable`。
+Aider 的安装命令由 Go 后端固定为 `uv tool install --force --python python3.12 --no-python-downloads ...`。这条路径只在选择 Aider 时执行；缺少 `uv` 或 Python 3.12 会返回 `PREREQUISITE_MISSING`。
 
 ## 开发与测试
 
-安装前端依赖并构建：
+Go 核心、发行工具和 RC 工具：
 
 ```bash
-cd frontend
-npm ci
-npm run build
+go vet ./...
+go test ./...
+go test -race ./...
+go run honnef.co/go/tools/cmd/staticcheck@2025.1.1 ./...
+go run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./...
 ```
-
-Python 3.12 契约和覆盖率：
-
-```bash
-python3.12 -m coverage run --branch -m unittest \
-  tests.test_core tests.test_cli tests.test_server \
-  tests.test_release_policy tests.test_edge_cases tests.test_rc_scripts
-python3.12 -m coverage report --fail-under=85
-python3.12 -m coverage json
-python3.12 -c "import json; s=json.load(open('build/coverage/coverage.json'))['files']['oneagent/installer.py']['summary']; assert s['percent_branches_covered'] == 100 and s['num_partial_branches'] == 0"
-```
-
-兼容测试：
-
-```bash
-bash tests/install_test.sh
-python3.12 tests/gui_smoke_test.py
-```
-
-React 与浏览器：
+React/Wails 测试：
 
 ```bash
 cd frontend
+npm ci
 npm run test:coverage
 npm run build
 npx playwright install chromium
-npm run e2e
+npm run test:e2e
+cd ..
+task test:native
 ```
 
-### Docker Linux Cleanroom
 
-这是开发和 CI 的可选测试资产，不是 OneAgent 的发行环境，也不代表 macOS 或其他平台验收：
+## Release Candidate
 
-本地 Docker cleanroom 会构建测试专用镜像，再以非 root 用户、全新 HOME 和 `--network none` 执行 Python、Bash、GUI、React、Chromium E2E 与发行策略扫描：
+真实锁定 Agent 安装（默认四个 npm Agent，不包含可选 Aider）：
 
 ```bash
-bash scripts/test_docker_cleanroom.sh
+go build -o bin/oneagent ./cmd/oneagent
+go run ./cmd/oneagent-rc verify-agents
+go run ./cmd/oneagent-rc adopted
 ```
 
-镜像构建阶段允许下载 apt、pip 和 npm 锁定依赖；正式测试容器不挂载源码、Docker Socket 或用户 HOME，只把结果写入 `build/docker-cleanroom/`。镜像不包含五个 Agent、`uv`、Provider Key 或用户配置，也不会上传到镜像仓库。
-
-Docker Desktop 在 macOS 上仍运行 Linux VM。该报告固定标记为 `linux`，只能证明 Linux cleanroom，不能替代 Darwin、APFS、`stat -f`、macOS PyInstaller、签名或公证验证。
-
-### 空白机器可用性验证
-
-常规套件都替换了 `Runtime.runner`，因此「Agent 真的装得上、装完真的能用」需要单独的三层验证。范围是 Codex 与 Claude Code，设计与结论见 [空白机器可用性验证计划](docs/blank-machine-verification-plan.md)。
+Provider 三协议 smoke 从受保护环境变量读取凭据和模型，不接受命令行 Key：
 
 ```bash
-# 装包命令契约：离线、毫秒级，随常规 CI 运行
-python3.12 -m unittest tests.test_install_contract
-
-# 真实安装：干净 HOME + 隔离 npm 前缀，断言可执行文件落到 PATH、版本等于锁定版本
-bash tests/real_install_test.sh
-ONEAGENT_REGISTRY=npmmirror bash tests/real_install_test.sh   # 同样验证镜像路径
-
-# 端到端可用性：需真实 Key，实际让两个 Agent 各回答一次请求
-ONEAGENT_API_KEY=... python3.12 scripts/agent_e2e_smoke.py --provider ppio
+ONEAGENT_PPIO_API_KEY=... \
+ONEAGENT_PPIO_OPENAI_MODEL=... \
+ONEAGENT_PPIO_ANTHROPIC_MODEL=... \
+ONEAGENT_PPIO_RESPONSES_MODEL=... \
+ONEAGENT_NOVITA_API_KEY=... \
+ONEAGENT_NOVITA_OPENAI_MODEL=... \
+ONEAGENT_NOVITA_ANTHROPIC_MODEL=... \
+ONEAGENT_NOVITA_RESPONSES_MODEL=... \
+go run ./cmd/oneagent-provider-smoke --provider all --timeout 30s
 ```
 
-真实安装与端到端不进常规 CI：前者每次提交都会打 registry，后者需要真实凭据。二者分别由 `release-candidate.yml` 与人工在发行前执行。
-
-### 真实 macOS Cleanroom
-
-真实 macOS cleanroom 是**已发布 macOS 产物**的验收依据，不是“必须先发布 macOS”的要求。当前架构的前端和 unsigned onedir 构建完成后，可以在真实 macOS 上运行：
-
-```bash
-ONEAGENT_PACKAGED_BINARY="$PWD/build/pyinstaller-dist/OneAgent/OneAgent" \
-bash tests/macos_cleanroom_test.sh
-```
-
-脚本要求真实 `uname -s == Darwin`，使用 `env -i`、临时 HOME/TMPDIR 和受控 PATH，验证源码 GUI、打包 GUI、随机本地端口、Cookie/Origin、五个配置适配器、备份以及目录 `0700`/文件 `0600`。执行前后会比对真实用户配置目标，发现污染立即失败。
-
-GitHub Actions 的 `ci.yml` macOS 作业（`macos-15` arm64 与 `macos-15-intel` x64）和手动 Release Candidate 运行该脚本，`tests/test_release_policy.py` 断言其契约不被弱化。普通 PR 与常规 CI 只使用 fake npm/uv，不下载真实 Agent，也不访问 PPIO/Novita；只有手动 Release Candidate 才在隔离 prefix/tool 目录中安装五个锁定版本并执行真实 Provider 冒烟。
-
-覆盖门槛：安全、备份、配置写入、权限、脱敏和 manifest 校验逻辑要求 100% 分支覆盖；Python 核心与 React 状态/API 层整体分支覆盖不低于 85%。
-
 ## 发行
 
-本机生成未签名预览包：
+在本机生成当前平台的未签名技术预览包：
 
 ```bash
-python3.12 -m pip install pyinstaller==6.21.0
-python3.12 scripts/build_release.py \
+go run ./cmd/oneagent-release build \
   --channel technical-preview-unsigned \
   --source
-python3.12 scripts/check_release.py release
+go run ./cmd/oneagent-release check release
 ```
 
-产物包括：
-
-- 当前平台 PyInstaller onedir ZIP。
-- 可选源码 ZIP。
-- `release-manifest-<platform>-<arch>.json`。
-- `SHA256SUMS-<platform>-<arch>.txt`。
-- 第三方许可证和五个 Agent 的锁定版本清单。
-
-PyInstaller 产物只声明其实际构建和验证过的目标环境。生成后的同一压缩包可以上传到 GitHub、官网、网盘或企业云盘；所有镜像必须保持相同 SHA-256，并记录渠道、链接、上传人、上传时间和撤回状态。
-
-`.github/workflows/release-candidate.yml` 是定义中的真实验收门禁：四平台真实安装五个锁定 Agent，并使用受保护的 `ONEAGENT_PPIO_API_KEY`、`ONEAGENT_NOVITA_API_KEY` 与对应协议模型变量执行低 token 请求；缺少任一 Key 或协议模型 ID 时流程会失败，不会退化成假通过。在 CI Secret 配置完成前它尚未运行（见上文“仍未取得证据的部分”）；在此之前，常规 CI 门禁以包体、许可证、secret、SHA-256、临时 HOME 启动和本地 Mock 流程为主。
+命令会构建 React、Wails 桌面二进制和纯 Go CLI，生成 macOS `.app` 或 Windows/Linux ZIP、可选源码 ZIP、第三方 notices、release manifest 和 SHA-256 清单。检查会拒绝 source map、远程资源、secret、Agent 二进制、语言运行时和不完整的锁定版本信息。
 
-在真实 PPIO/Novita 低权限 Key 尚未配置到受保护 CI Secret 前，可以使用 `apiproxy` 档案做本地三协议预检。该档案分别保留 OpenAI、Anthropic、Responses 三个模型槽位，当前统一使用 `openai/gpt-5.6-terra`；`openai/gpt-5.6-luna` 只支持两类协议，不作为三协议预检默认模型。
-
-```bash
-python3 scripts/provider_rc_smoke.py \
-  --provider apiproxy \
-  --api-key-json ~/.codex/auth.json \
-  --api-key-field OPENAI_API_KEY \
-  --timeout 45
-```
-
-此命令只读取本机 JSON 中的 Key，不会把 Key 放入命令行值或输出。`--provider all` 仍严格只运行 PPIO 和 Novita；代理预检成功不能替代正式 RC 验收。详细边界见 [Provider RC 测试说明](docs/provider-rc-testing.md)。
-
-当前只发布明确标记的 `technical-preview-unsigned`。当前阶段不做平台签名、公证和商店分发；Stable 门禁（macOS 签名/公证、Windows Authenticode）仍然有效并由 `scripts/build_release.py` 产物级强制，只是当前不走 Stable 渠道。
+Wails 仍处于 Alpha，当前不发布 Stable，不做平台签名、公证或商店分发。Stable 的签名门禁保留在后续发行阶段。
 
 ## 文档
 
-- [产品边界基线](docs/product-boundary-baseline.md)
-- [公开分发站运营与发布手册](docs/public-site-operations.md)
-- [独立公开站与机器生成发行索引 ADR](docs/decisions/ADR-006-public-site-and-generated-release-index.md)
-- [多渠道分发与合规政策](docs/distribution-compliance-policy.md)
-- [渠道无关的二进制分发 ADR](docs/decisions/ADR-005-channel-neutral-distribution-and-compliance.md)
-- [三平台 Python 内核与版本锁定 ADR](docs/decisions/ADR-003-three-platform-python-core-and-release-policy.md)
-- [按 Agent 协议验证 ADR](docs/decisions/ADR-004-per-agent-protocol-verification.md)
-- [React 前端实现与发布门禁](docs/frontend-component-redesign-plan.md)
+- [Wails v3 迁移收尾计划](docs/wails-v3-migration-plan.md)
+- [发行与合规政策](docs/distribution-compliance-policy.md)
+- [公开站运营手册](docs/public-site-operations.md)
 - [Provider RC 测试说明](docs/provider-rc-testing.md)
-- [前端管理控制台改造计划](docs/frontend-management-console-plan.md)
-- [CC Switch 参考笔记](docs/cc-switch-reference-notes.md)
-- [用户使用文档](docs/ai-agent-kit/00-start-here.md)
-- [配置工具选择](docs/ai-agent-kit/03-config-tools.md)
-- [CC Switch 可选配置说明](docs/ai-agent-kit/tools/cc-switch.md)
-
-CC Switch 仅为可选文档，不自动安装、不进入运行依赖，也不替代 Provider API 服务。
+- [AI Agent Kit](docs/ai-agent-kit/00-start-here.md)
+- [Wails 架构 ADR](docs/decisions/ADR-007-wails-v3-go-migration.md)
+- [按 Agent 协议验证 ADR](docs/decisions/ADR-004-per-agent-protocol-verification.md)
+- [历史 Python 发行 ADR（已废弃）](docs/decisions/ADR-003-three-platform-python-core-and-release-policy.md)
diff --git a/Taskfile.yml b/Taskfile.yml
new file mode 100644
index 00000000..a9c486a0
--- /dev/null
+++ b/Taskfile.yml
@@ -0,0 +1,79 @@
+version: '3'
+
+vars:
+  APP_NAME: oneagent-desktop
+  BIN_DIR: bin
+  VITE_PORT: '{{.WAILS_VITE_PORT | default 9245}}'
+  # Target OS for build/run. Defaults to the host OS; override with GOOS=... to
+  # cross-compile (only windows supports cross-compilation, see build/*/Taskfile.yml).
+  GOOS: '{{.GOOS | default OS}}'
+  WAILS_MODULE: github.com/wailsapp/wails/v3
+  WAILS_VERSION: v3.0.0-beta.2
+  # Pinned Wails CLI (see build/tool-versions.env); never rely on a global wails3.
+  WAILS3: go run {{.WAILS_MODULE}}/cmd/wails3@{{.WAILS_VERSION}}
+
+includes:
+  common: ./build/Taskfile.yml
+  darwin: ./build/darwin/Taskfile.yml
+  linux: ./build/linux/Taskfile.yml
+  windows: ./build/windows/Taskfile.yml
+
+tasks:
+  build:
+    summary: Builds the desktop application for {{.GOOS}}
+    cmds:
+      - task: '{{.GOOS}}:build'
+        vars:
+          ARCH: '{{.ARCH}}'
+          DEV: '{{.DEV}}'
+          OUTPUT: '{{.OUTPUT}}'
+
+  run:
+    summary: Runs the built desktop application
+    cmds:
+      - task: '{{.GOOS}}:run'
+
+  dev:
+    summary: Runs the application in development mode (vite HMR + Go rebuild on change)
+    cmds:
+      - '{{.WAILS3}} dev -config ./build/config.yml -port {{.VITE_PORT}}'
+
+  test:go:
+    summary: Run Go backend tests
+    cmds:
+      - go test ./...
+
+  build:cli:
+    summary: Build the headless Go CLI
+    cmds:
+      - mkdir -p {{.BIN_DIR}}
+      - go build -o {{.BIN_DIR}}/oneagent ./cmd/oneagent
+
+  generate:bindings:
+    summary: Regenerate Wails TypeScript bindings
+    cmds:
+      - task: common:generate:bindings
+
+  build:frontend:
+    summary: Build the React frontend
+    cmds:
+      - task: common:build:frontend
+
+  build:desktop:
+    summary: Build the production Wails desktop binary for the host OS
+    cmds:
+      - task: build
+
+  test:e2e:
+    summary: Run the Wails server binding browser test
+    deps:
+      - build:frontend
+    cmds:
+      - cd frontend && pnpm run test:e2e
+
+  test:native:
+    summary: Start the native Wails binary and require a GetStatus binding call
+    deps:
+      - build:desktop
+    cmds:
+      - go run ./cmd/oneagent-native-smoke -binary ./{{.BIN_DIR}}/{{.APP_NAME}}
diff --git a/build/Taskfile.yml b/build/Taskfile.yml
new file mode 100644
index 00000000..2eee4b7a
--- /dev/null
+++ b/build/Taskfile.yml
@@ -0,0 +1,70 @@
+version: '3'
+
+tasks:
+  go:mod:tidy:
+    summary: Runs `go mod tidy`
+    internal: true
+    # darwin:build:universal runs its per-arch builds as parallel deps; two
+    # `go mod tidy` processes racing on go.mod can corrupt it.
+    run: once
+    cmds:
+      - go mod tidy
+
+  install:frontend:deps:
+    summary: Install frontend dependencies (pnpm only)
+    run: once
+    dir: frontend
+    sources:
+      - package.json
+      - pnpm-lock.yaml
+    generates:
+      - node_modules
+    preconditions:
+      - sh: pnpm --version
+        msg: "pnpm not found. Install it first: https://pnpm.io/installation"
+    cmds:
+      - pnpm install
+
+  build:frontend:
+    summary: Build the React frontend (tsc --noEmit runs as part of the build script)
+    # Universal builds run per-arch builds as parallel deps, each depending on
+    # this task; without run:once the two executions race on frontend/bindings.
+    run: once
+    dir: frontend
+    sources:
+      - "**/*"
+      - exclude: node_modules/**/*
+    generates:
+      - dist/**/*
+    deps:
+      - task: install:frontend:deps
+      - task: generate:bindings
+    cmds:
+      - pnpm run build
+    env:
+      PRODUCTION: '{{if eq .DEV "true"}}false{{else}}true{{end}}'
+
+  generate:bindings:
+    summary: Regenerate Wails TypeScript bindings with the pinned Wails CLI
+    run: once
+    deps:
+      - task: go:mod:tidy
+    sources:
+      - "**/*.go"
+      - go.mod
+      - go.sum
+      - exclude: frontend/**/*
+    generates:
+      - frontend/bindings/**/*
+    cmds:
+      - '{{.WAILS3}} generate bindings -f "-tags wails" -ts -i -d frontend/bindings ./cmd/oneagent-desktop'
+
+  dev:frontend:
+    summary: Runs the Vite dev server (used by `task dev`)
+    deps:
+      - task: install:frontend:deps
+    dir: frontend
+    cmds:
+      # Vite 8 binds to [::1] only by default, but the Wails dev asset proxy
+      # dials localhost with forced IPv4 — bind 127.0.0.1 so they can meet.
+      - pnpm run dev --host 127.0.0.1 --port {{.VITE_PORT}} --strictPort
diff --git a/build/config.yml b/build/config.yml
new file mode 100644
index 00000000..a0d1ce0a
--- /dev/null
+++ b/build/config.yml
@@ -0,0 +1,37 @@
+version: '3'
+
+info:
+  companyName: "MaimoryLab"
+  productName: "OneAgent"
+  productIdentifier: "com.maimorylab.oneagent"
+  description: "Local AI development environment activator"
+  copyright: "(c) 2026 MaimoryLab"
+  version: "0.3.0-dev"
+
+dev_mode:
+  root_path: .
+  log_level: warn
+  debounce: 500
+  ignore:
+    dir:
+      - .git
+      - node_modules
+      - frontend
+      - bin
+    file:
+      - .DS_Store
+      - .gitkeep
+      - .keep
+      - "*_test.go"
+    watched_extension:
+      - "*.go"
+    git_ignore: true
+  executes:
+    # Dev build regenerates bindings and the frontend dist via task deps; the
+    # running app itself loads the frontend from the background Vite server.
+    - cmd: task build DEV=true
+      type: blocking
+    - cmd: task common:dev:frontend
+      type: background
+    - cmd: task run
+      type: primary
diff --git a/build/darwin/Taskfile.yml b/build/darwin/Taskfile.yml
new file mode 100644
index 00000000..8f9f8383
--- /dev/null
+++ b/build/darwin/Taskfile.yml
@@ -0,0 +1,48 @@
+version: '3'
+
+includes:
+  common: ../Taskfile.yml
+
+tasks:
+  build:
+    summary: Builds the macOS desktop binary (native only, no Docker cross-compilation)
+    deps:
+      - task: common:go:mod:tidy
+      - task: common:build:frontend
+        vars:
+          DEV:
+            ref: .DEV
+    preconditions:
+      - sh: test "$(uname -s)" = "Darwin"
+        msg: "macOS binaries require CGO and must be built on macOS."
+    cmds:
+      - go build {{.BUILD_FLAGS}} -o "{{.OUTPUT}}" ./cmd/oneagent-desktop
+    vars:
+      BUILD_FLAGS: '{{if eq .DEV "true"}}-tags wails -buildvcs=false -gcflags=all="-l"{{else}}-tags wails,production -trimpath -buildvcs=false -ldflags="-w -s"{{end}}'
+      OUTPUT: '{{.OUTPUT | default (printf "%s/%s" .BIN_DIR .APP_NAME)}}'
+    env:
+      GOOS: darwin
+      CGO_ENABLED: 1
+      GOARCH: '{{.ARCH | default ARCH}}'
+      CGO_CFLAGS: "-mmacosx-version-min=12.0"
+      CGO_LDFLAGS: "-mmacosx-version-min=12.0"
+      MACOSX_DEPLOYMENT_TARGET: "12.0"
+
+  build:universal:
+    summary: Builds a darwin universal binary (arm64 + amd64)
+    deps:
+      - task: build
+        vars:
+          ARCH: amd64
+          OUTPUT: '{{.BIN_DIR}}/{{.APP_NAME}}-amd64'
+      - task: build
+        vars:
+          ARCH: arm64
+          OUTPUT: '{{.BIN_DIR}}/{{.APP_NAME}}-arm64'
+    cmds:
+      - lipo -create -output "{{.BIN_DIR}}/{{.APP_NAME}}" "{{.BIN_DIR}}/{{.APP_NAME}}-amd64" "{{.BIN_DIR}}/{{.APP_NAME}}-arm64"
+      - rm "{{.BIN_DIR}}/{{.APP_NAME}}-amd64" "{{.BIN_DIR}}/{{.APP_NAME}}-arm64"
+
+  run:
+    cmds:
+      - '"{{.BIN_DIR}}/{{.APP_NAME}}"'
diff --git a/build/linux/Taskfile.yml b/build/linux/Taskfile.yml
new file mode 100644
index 00000000..64c9bfa2
--- /dev/null
+++ b/build/linux/Taskfile.yml
@@ -0,0 +1,30 @@
+version: '3'
+
+includes:
+  common: ../Taskfile.yml
+
+tasks:
+  build:
+    summary: Builds the Linux desktop binary (native only, no Docker cross-compilation)
+    deps:
+      - task: common:go:mod:tidy
+      - task: common:build:frontend
+        vars:
+          DEV:
+            ref: .DEV
+    preconditions:
+      - sh: test "$(uname -s)" = "Linux"
+        msg: "Linux binaries require CGO (WebKitGTK) and must be built on Linux."
+    cmds:
+      - go build {{.BUILD_FLAGS}} -o "{{.OUTPUT}}" ./cmd/oneagent-desktop
+    vars:
+      BUILD_FLAGS: '{{if eq .DEV "true"}}-tags wails -buildvcs=false -gcflags=all="-l"{{else}}-tags wails,production -trimpath -buildvcs=false -ldflags="-w -s"{{end}}'
+      OUTPUT: '{{.OUTPUT | default (printf "%s/%s" .BIN_DIR .APP_NAME)}}'
+    env:
+      GOOS: linux
+      CGO_ENABLED: 1
+      GOARCH: '{{.ARCH | default ARCH}}'
+
+  run:
+    cmds:
+      - '"{{.BIN_DIR}}/{{.APP_NAME}}"'
diff --git a/build/tool-versions.env b/build/tool-versions.env
new file mode 100644
index 00000000..78a18e6a
--- /dev/null
+++ b/build/tool-versions.env
@@ -0,0 +1,8 @@
+# Pinned migration toolchain. Update these values only after the native spike
+# and binding-diff checks have been rerun on all four supported targets.
+GO_VERSION=1.26
+NODE_VERSION=22
+WAILS_VERSION=v3.0.0-beta.2
+WAILS_CLI_VERSION=v3.0.0-beta.2
+WAILS_RUNTIME_VERSION=3.0.0-alpha2.117
+TASK_VERSION=v3.40.1-patched3
diff --git a/build/windows/Taskfile.yml b/build/windows/Taskfile.yml
new file mode 100644
index 00000000..444b38be
--- /dev/null
+++ b/build/windows/Taskfile.yml
@@ -0,0 +1,27 @@
+version: '3'
+
+includes:
+  common: ../Taskfile.yml
+
+tasks:
+  build:
+    summary: Builds the Windows desktop binary (pure-Go cross-compile works from any host)
+    deps:
+      - task: common:go:mod:tidy
+      - task: common:build:frontend
+        vars:
+          DEV:
+            ref: .DEV
+    cmds:
+      - go build {{.BUILD_FLAGS}} -o "{{.OUTPUT}}" ./cmd/oneagent-desktop
+    vars:
+      BUILD_FLAGS: '{{if eq .DEV "true"}}-tags wails -buildvcs=false -gcflags=all="-l"{{else}}-tags wails,production -trimpath -buildvcs=false -ldflags="-w -s -H windowsgui"{{end}}'
+      OUTPUT: '{{.OUTPUT | default (printf "%s/%s.exe" .BIN_DIR .APP_NAME)}}'
+    env:
+      GOOS: windows
+      CGO_ENABLED: 0
+      GOARCH: '{{.ARCH | default ARCH}}'
+
+  run:
+    cmds:
+      - '"{{.BIN_DIR}}/{{.APP_NAME}}.exe"'
diff --git a/cmd/oneagent-desktop/core.go b/cmd/oneagent-desktop/core.go
new file mode 100644
index 00000000..c382e397
--- /dev/null
+++ b/cmd/oneagent-desktop/core.go
@@ -0,0 +1,9 @@
+//go:build wails && !e2e
+
+package main
+
+import "github.com/MaimoryLab/OneAgent/internal/app"
+
+func newDesktopUseCases() *app.UseCases {
+	return app.NewUseCasesFromEnvironment()
+}
diff --git a/cmd/oneagent-desktop/core_e2e.go b/cmd/oneagent-desktop/core_e2e.go
new file mode 100644
index 00000000..b5eb0a9b
--- /dev/null
+++ b/cmd/oneagent-desktop/core_e2e.go
@@ -0,0 +1,122 @@
+//go:build wails && e2e
+
+package main
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/app"
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+)
+
+func newDesktopUseCases() *app.UseCases {
+	info := platform.Current()
+	home := platform.ResolveHome(nil, info.OS)
+	return app.NewUseCasesWithProviderClient(app.StatusOptions{
+		Home:        home,
+		Platform:    info,
+		Runner:      newE2ERunner(),
+		Environment: map[string]string{"HOME": home},
+	}, provider.NewClient(e2eProviderDoer{}))
+}
+
+type e2eRunner struct {
+	mu        sync.RWMutex
+	agents    map[string]catalog.Agent
+	byPackage map[string]string
+	installed map[string]string
+}
+
+func newE2ERunner() *e2eRunner {
+	runner := &e2eRunner{
+		agents:    map[string]catalog.Agent{},
+		byPackage: map[string]string{},
+		installed: map[string]string{},
+	}
+	manifest, err := catalog.LoadEmbedded()
+	if err != nil {
+		return runner
+	}
+	runner.agents = manifest.Agents
+	for id, agent := range manifest.Agents {
+		if agent.Package != nil {
+			runner.byPackage[agent.Package.Name+"@"+agent.Package.Version] = id
+		}
+	}
+	return runner
+}
+
+func (r *e2eRunner) LookPath(command string) (string, bool) {
+	// The browser build pretends Node is present and uv is not, so the runtime
+	// section renders one installed row and one installable row without any
+	// download happening.
+	if command == "npm" || command == "node" {
+		return "/oneagent-e2e/" + command, true
+	}
+	r.mu.RLock()
+	_, ok := r.installed[command]
+	r.mu.RUnlock()
+	if !ok {
+		return "", false
+	}
+	return "/oneagent-e2e/" + command, true
+}
+
+func (r *e2eRunner) Run(_ context.Context, argv []string, _ map[string]string, _ time.Duration) (process.Result, error) {
+	result := process.Result{Args: append([]string(nil), argv...), ExitCode: 0}
+	if len(argv) >= 4 && argv[1] == "view" && argv[3] == "dist.integrity" {
+		if id, ok := r.byPackage[argv[2]]; ok && r.agents[id].Package != nil && r.agents[id].Package.Integrity != nil {
+			result.Stdout = *r.agents[id].Package.Integrity + "\n"
+			return result, nil
+		}
+		result.ExitCode = 1
+		return result, nil
+	}
+	if len(argv) >= 4 && argv[1] == "install" && argv[2] == "-g" {
+		if id, ok := r.byPackage[argv[3]]; ok {
+			agent := r.agents[id]
+			r.mu.Lock()
+			r.installed[agent.Command] = agent.Package.Version
+			r.mu.Unlock()
+		}
+		return result, nil
+	}
+	if len(argv) >= 2 && argv[len(argv)-1] == "--version" {
+		command := filepath.Base(argv[0])
+		r.mu.RLock()
+		version := r.installed[command]
+		r.mu.RUnlock()
+		if version != "" {
+			result.Stdout = command + " " + version + "\n"
+		}
+	}
+	return result, nil
+}
+
+type e2eProviderDoer struct{}
+
+func (e2eProviderDoer) Do(request *http.Request) (*http.Response, error) {
+	body := ""
+	if request.Method == http.MethodGet && strings.HasSuffix(request.URL.Path, "/models") {
+		body = `{"data":[{"id":"oneagent-e2e-model"}]}`
+	}
+	status := http.StatusNoContent
+	if body != "" {
+		status = http.StatusOK
+	}
+	return &http.Response{
+		StatusCode: status,
+		Header:     make(http.Header),
+		Body:       io.NopCloser(strings.NewReader(body)),
+		Request:    request,
+	}, nil
+}
diff --git a/cmd/oneagent-desktop/main.go b/cmd/oneagent-desktop/main.go
new file mode 100644
index 00000000..35a7ff8b
--- /dev/null
+++ b/cmd/oneagent-desktop/main.go
@@ -0,0 +1,12 @@
+//go:build !wails
+
+package main
+
+import "fmt"
+
+func main() {
+	// The default build is intentionally headless and dependency-free. Native
+	// Wails builds opt into the wails tag so Go tests and the CLI do not link a
+	// platform WebView by accident.
+	fmt.Println("OneAgent desktop shell: build with -tags wails")
+}
diff --git a/cmd/oneagent-desktop/main_wails.go b/cmd/oneagent-desktop/main_wails.go
new file mode 100644
index 00000000..62aba7ae
--- /dev/null
+++ b/cmd/oneagent-desktop/main_wails.go
@@ -0,0 +1,85 @@
+//go:build wails
+
+package main
+
+import (
+	"log/slog"
+	"os"
+	"sync"
+	"time"
+
+	oneagent "github.com/MaimoryLab/OneAgent"
+	"github.com/MaimoryLab/OneAgent/internal/binding"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+	"github.com/wailsapp/wails/v3/pkg/application"
+)
+
+func main() {
+	var appInstance *application.App
+	core := newDesktopUseCases()
+	var nativeSmokeOnce sync.Once
+	var afterGetStatus func()
+	if os.Getenv("ONEAGENT_NATIVE_SMOKE") == "1" {
+		afterGetStatus = func() {
+			nativeSmokeOnce.Do(func() {
+				if result := os.Getenv("ONEAGENT_NATIVE_SMOKE_RESULT"); result != "" {
+					_ = os.WriteFile(result, []byte("ok\n"), 0o600)
+				}
+				time.AfterFunc(250*time.Millisecond, func() {
+					if appInstance != nil {
+						appInstance.Quit()
+					}
+				})
+			})
+		}
+	}
+	services := binding.NewServicesWithOptions(core, func(url string) error {
+		current := application.Get()
+		if current == nil || current.Browser == nil {
+			return oneerrors.New(oneerrors.InternalError, "Desktop browser is not ready")
+		}
+		return current.Browser.OpenURL(url)
+	}, binding.ServicesOptions{
+		AfterGetStatus: afterGetStatus,
+		InstallOutput: func(output process.Output) {
+			if appInstance != nil {
+				appInstance.Event.Emit("oneagent:install-output", output)
+			}
+		},
+	})
+
+	// No Route or RawMessageHandler is configured. The default Wails transport
+	// is internal IPC; the production app does not expose a business HTTP port.
+	appInstance = application.New(application.Options{
+		Name:        "OneAgent",
+		Description: "Local AI development environment activator",
+		LogLevel:    slog.LevelInfo,
+		Services: []application.Service{
+			application.NewServiceWithOptions(services.Status, application.ServiceOptions{MarshalError: oneerrors.Marshal}),
+			application.NewServiceWithOptions(services.Provider, application.ServiceOptions{MarshalError: oneerrors.Marshal}),
+			application.NewServiceWithOptions(services.Agent, application.ServiceOptions{MarshalError: oneerrors.Marshal}),
+			application.NewServiceWithOptions(services.Profile, application.ServiceOptions{MarshalError: oneerrors.Marshal}),
+			application.NewServiceWithOptions(services.Runtime, application.ServiceOptions{MarshalError: oneerrors.Marshal}),
+		},
+		MarshalError: oneerrors.Marshal,
+		Assets: application.AssetOptions{
+			Handler:        application.AssetFileServerFS(oneagent.FrontendAssets),
+			DisableLogging: true,
+		},
+		Mac: application.MacOptions{ApplicationShouldTerminateAfterLastWindowClosed: true},
+	})
+	if !application.System.IsServer() {
+		appInstance.Window.NewWithOptions(application.WebviewWindowOptions{
+			Title:  "OneAgent",
+			Width:  1180,
+			Height: 760,
+			URL:    "/",
+		})
+	}
+	if err := appInstance.Run(); err != nil {
+		// Do not print an arbitrary Wails error containing binding arguments.
+		_, _ = os.Stderr.WriteString("OneAgent desktop failed to start\n")
+		os.Exit(1)
+	}
+}
diff --git a/cmd/oneagent-native-smoke/main.go b/cmd/oneagent-native-smoke/main.go
new file mode 100644
index 00000000..94c9530f
--- /dev/null
+++ b/cmd/oneagent-native-smoke/main.go
@@ -0,0 +1,67 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"time"
+)
+
+func main() {
+	binary := flag.String("binary", "", "path to the native OneAgent desktop binary")
+	timeout := flag.Duration("timeout", 20*time.Second, "maximum time to wait for GetStatus")
+	flag.Parse()
+	if err := run(*binary, *timeout); err != nil {
+		_, _ = fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func run(binary string, timeout time.Duration) error {
+	if binary == "" {
+		return fmt.Errorf("-binary is required")
+	}
+	if runtime.GOOS == "windows" && filepath.Ext(binary) == "" {
+		if _, err := os.Stat(binary + ".exe"); err == nil {
+			binary += ".exe"
+		}
+	}
+	home, err := os.MkdirTemp("", "oneagent-native-smoke-")
+	if err != nil {
+		return fmt.Errorf("create temporary HOME: %w", err)
+	}
+	defer os.RemoveAll(home)
+	result := filepath.Join(home, "get-status")
+	command := exec.Command(binary)
+	command.Stdout = os.Stdout
+	command.Stderr = os.Stderr
+	command.Env = append(os.Environ(),
+		"HOME="+home,
+		"USERPROFILE="+home,
+		"ONEAGENT_HOME="+home,
+		"ONEAGENT_NATIVE_SMOKE=1",
+		"ONEAGENT_NATIVE_SMOKE_RESULT="+result,
+	)
+	if err := command.Start(); err != nil {
+		return fmt.Errorf("start desktop app: %w", err)
+	}
+	exited := make(chan error, 1)
+	go func() { exited <- command.Wait() }()
+	select {
+	case err := <-exited:
+		if err != nil {
+			return fmt.Errorf("desktop app exited before GetStatus: %w", err)
+		}
+	case <-time.After(timeout):
+		_ = command.Process.Kill()
+		<-exited
+		return fmt.Errorf("timed out waiting for the desktop GetStatus binding")
+	}
+	if content, err := os.ReadFile(result); err != nil || string(content) != "ok\n" {
+		return fmt.Errorf("desktop app exited without calling GetStatus through the binding")
+	}
+	return nil
+}
diff --git a/cmd/oneagent-provider-smoke/main.go b/cmd/oneagent-provider-smoke/main.go
new file mode 100644
index 00000000..d773a4bf
--- /dev/null
+++ b/cmd/oneagent-provider-smoke/main.go
@@ -0,0 +1,91 @@
+// Command oneagent-provider-smoke runs the low-token checks for every Provider
+// declared in providers.lock.json, as used by release-candidate verification.
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+)
+
+func main() { os.Exit(run(os.Args[1:])) }
+
+func run(args []string) int {
+	flags := flag.NewFlagSet("oneagent-provider-smoke", flag.ContinueOnError)
+	flags.SetOutput(os.Stderr)
+	providerID := flags.String("provider", "all", "Provider ID or all")
+	timeout := flags.Duration("timeout", 30*time.Second, "per-request timeout")
+	if err := flags.Parse(args); err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			return 0
+		}
+		return 2
+	}
+	ids := catalog.ProviderIDs()
+	if *providerID != "all" {
+		ids = []string{*providerID}
+	}
+	client := provider.NewClientWithLimits(nil, *timeout, 1<<20)
+	for _, id := range ids {
+		if err := smoke(context.Background(), client, id, *timeout); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return 1
+		}
+	}
+	return 0
+}
+
+func smoke(parent context.Context, client *provider.Client, id string, timeout time.Duration) error {
+	if _, ok := catalog.ProviderByID(id); !ok {
+		return fmt.Errorf("unknown Provider %q", id)
+	}
+	prefix := strings.ToUpper(id)
+	key := os.Getenv("ONEAGENT_" + prefix + "_API_KEY")
+	models := map[string]string{
+		provider.ProtocolOpenAI:    os.Getenv("ONEAGENT_" + prefix + "_OPENAI_MODEL"),
+		provider.ProtocolAnthropic: os.Getenv("ONEAGENT_" + prefix + "_ANTHROPIC_MODEL"),
+		provider.ProtocolResponses: os.Getenv("ONEAGENT_" + prefix + "_RESPONSES_MODEL"),
+	}
+	for protocolID, model := range models {
+		if strings.TrimSpace(model) == "" {
+			return fmt.Errorf("%s: ONEAGENT_%s_%s_MODEL is required", id, prefix, strings.ToUpper(protocolID))
+		}
+	}
+	openAIBase := os.Getenv("ONEAGENT_" + prefix + "_OPENAI_BASE")
+	anthropicBase := os.Getenv("ONEAGENT_" + prefix + "_ANTHROPIC_BASE")
+	if key == "" {
+		return errors.New("ONEAGENT_" + prefix + "_API_KEY is required")
+	}
+	ctx, cancel := context.WithTimeout(parent, timeout)
+	defer cancel()
+	listing, err := client.ListModels(ctx, id, key, openAIBase)
+	if err != nil {
+		return fmt.Errorf("%s models: %w", id, err)
+	}
+	if !listing.Reachable || listing.Status < 200 || listing.Status >= 300 {
+		return fmt.Errorf("%s models: HTTP %d: %s", id, listing.Status, listing.Message)
+	}
+	fmt.Printf("%s models: HTTP %d\n", id, listing.Status)
+	for _, protocolID := range []string{provider.ProtocolOpenAI, provider.ProtocolResponses, provider.ProtocolAnthropic} {
+		base := openAIBase
+		if protocolID == provider.ProtocolAnthropic {
+			base = anthropicBase
+		}
+		result, probeErr := client.Probe(ctx, protocolID, id, key, models[protocolID], base)
+		if probeErr != nil {
+			return fmt.Errorf("%s %s: %w", id, protocolID, probeErr)
+		}
+		if !result.OK {
+			return fmt.Errorf("%s %s: HTTP %d: %s", id, protocolID, result.Status, result.Message)
+		}
+		fmt.Printf("%s %s: HTTP %d\n", id, protocolID, result.Status)
+	}
+	return nil
+}
diff --git a/cmd/oneagent-rc/main.go b/cmd/oneagent-rc/main.go
new file mode 100644
index 00000000..f21a7327
--- /dev/null
+++ b/cmd/oneagent-rc/main.go
@@ -0,0 +1,434 @@
+// Command oneagent-rc contains the networked release-candidate checks that are
+// intentionally kept outside the desktop and headless application binaries.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	"github.com/MaimoryLab/OneAgent/internal/install"
+)
+
+var defaultAgents = []string{"codex", "claude-code", "opencode", "kilo-cli"}
+
+type isolation struct {
+	root string
+	home string
+	env  []string
+	cli  string
+}
+
+type installResult struct {
+	Agent   string `json:"agent"`
+	Status  string `json:"status"`
+	Version string `json:"version"`
+}
+
+type installPayload struct {
+	OK      bool            `json:"ok"`
+	Results []installResult `json:"results"`
+	Log     string          `json:"log"`
+}
+
+func main() { os.Exit(run(os.Args[1:])) }
+
+func run(args []string) int {
+	if len(args) == 0 {
+		usage()
+		return 2
+	}
+	root, err := repositoryRoot()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return 1
+	}
+	switch args[0] {
+	case "verify-agents":
+		if err := verifyAgents(root, args[1:], false); err != nil {
+			if errors.Is(err, flag.ErrHelp) {
+				return 0
+			}
+			fmt.Fprintln(os.Stderr, err)
+			return 1
+		}
+	case "adopted":
+		if err := verifyAgents(root, args[1:], true); err != nil {
+			if errors.Is(err, flag.ErrHelp) {
+				return 0
+			}
+			fmt.Fprintln(os.Stderr, err)
+			return 1
+		}
+	default:
+		usage()
+		return 2
+	}
+	return 0
+}
+
+func usage() {
+	fmt.Fprintln(os.Stderr, "usage: oneagent-rc verify-agents [--agents ids] [--registry id-or-url]")
+	fmt.Fprintln(os.Stderr, "       oneagent-rc adopted [--agents codex,claude-code] [--timeout seconds]")
+}
+
+func repositoryRoot() (string, error) {
+	directory, err := os.Getwd()
+	if err != nil {
+		return "", err
+	}
+	for {
+		if _, err := os.Stat(filepath.Join(directory, "go.mod")); err == nil {
+			return directory, nil
+		}
+		parent := filepath.Dir(directory)
+		if parent == directory {
+			return "", errors.New("could not locate the OneAgent repository root")
+		}
+		directory = parent
+	}
+}
+
+func verifyAgents(root string, args []string, adopted bool) error {
+	flags := flag.NewFlagSet("oneagent-rc", flag.ContinueOnError)
+	flags.SetOutput(os.Stderr)
+	idsValue := strings.Join(defaultAgents, ",")
+	if adopted {
+		idsValue = "codex,claude-code"
+	}
+	ids := flags.String("agents", idsValue, "comma-separated Agent IDs")
+	registry := flags.String("registry", "", "npm mirror id or HTTPS URL")
+	timeout := flags.Int("timeout", 900, "seconds per package operation")
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+	agentIDs := splitIDs(*ids)
+	if len(agentIDs) == 0 {
+		return errors.New("at least one Agent is required")
+	}
+	manifest, err := catalog.LoadEmbedded()
+	if err != nil {
+		return err
+	}
+	for _, id := range agentIDs {
+		agent, ok := manifest.Agents[id]
+		if !ok || agent.ConfigMode != "auto" || agent.Package == nil {
+			return fmt.Errorf("%s is not an installable auto Agent", id)
+		}
+		if agent.Package.Manager != "npm" {
+			return fmt.Errorf("%s uses an optional package runtime; omit it from this check", id)
+		}
+	}
+
+	isolated, cleanup, err := newIsolation(root)
+	if err != nil {
+		return err
+	}
+	defer cleanup()
+	ctx := context.Background()
+	installArgs := []string{
+		"--agent", strings.Join(agentIDs, ","),
+		"--install-agent", "--locked-version", "--check-agent-only", "--json",
+		"--home", isolated.home,
+	}
+	if *registry != "" {
+		installArgs = append(installArgs, "--registry", *registry)
+	}
+	result, err := runCLI(ctx, isolated, installArgs...)
+	if err != nil {
+		return err
+	}
+	if result.ExitCode != 0 {
+		return fmt.Errorf("locked Agent installation failed: %s", compact(result.Stdout+" "+result.Stderr))
+	}
+	var payload installPayload
+	if err := json.Unmarshal([]byte(result.Stdout), &payload); err != nil {
+		return fmt.Errorf("decode OneAgent install result: %w", err)
+	}
+	if !payload.OK {
+		return fmt.Errorf("locked Agent installation reported failure: %s", compact(payload.Log))
+	}
+	byID := make(map[string]installResult, len(payload.Results))
+	for _, item := range payload.Results {
+		byID[item.Agent] = item
+	}
+	for _, id := range agentIDs {
+		agent := manifest.Agents[id]
+		item, ok := byID[id]
+		if !ok || item.Status != "installed" {
+			return fmt.Errorf("%s was not installed (status %q)", id, item.Status)
+		}
+		executable, ok := lookPath(isolated.env, agent.Command)
+		if !ok {
+			return fmt.Errorf("%s did not land on the isolated PATH", id)
+		}
+		versionValue, err := commandVersion(ctx, isolated.env, executable, agent.VersionArgs)
+		if err != nil {
+			return fmt.Errorf("read %s version: %w", id, err)
+		}
+		if versionValue != agent.Package.Version {
+			return fmt.Errorf("%s reports %s, lock requires %s", id, versionValue, agent.Package.Version)
+		}
+		fmt.Printf("%s: %s\n", id, versionValue)
+	}
+	if adopted {
+		return checkAdoption(ctx, isolated, agentIDs, time.Duration(*timeout)*time.Second)
+	}
+	return nil
+}
+
+func checkAdoption(ctx context.Context, isolated isolation, agentIDs []string, timeout time.Duration) error {
+	const key = "oneagent-discard-key"
+	configure := []string{
+		"--agent", strings.Join(agentIDs, ","),
+		"--provider", "custom", "--api-base-url", "http://127.0.0.1:9/openai",
+		"--api-key", key, "--model", "oneagent-discard-model", "--skip-test", "--json",
+		"--home", isolated.home,
+	}
+	result, err := runCLI(ctx, isolated, configure...)
+	if err != nil {
+		return err
+	}
+	if result.ExitCode != 0 {
+		return fmt.Errorf("discard-endpoint configuration failed: %s", compact(result.Stdout+" "+result.Stderr))
+	}
+	for _, id := range agentIDs {
+		command, argv, ok := adoptionCommand(id)
+		if !ok {
+			continue
+		}
+		executable, found := lookPath(isolated.env, command)
+		if !found {
+			return fmt.Errorf("%s is not on the isolated PATH", id)
+		}
+		env := append([]string(nil), isolated.env...)
+		env = appendEnv(env, "CI", "1")
+		env = appendEnv(env, "NO_COLOR", "1")
+		env = appendEnv(env, "TERM", "dumb")
+		env = appendEnv(env, "ONEAGENT_API_KEY_CODEX", key)
+		commandArgs := append([]string{executable}, argv...)
+		commandResult, runErr := runWithEnv(ctx, env, timeout, commandArgs...)
+		output := compact(commandResult.Stdout + " " + commandResult.Stderr)
+		if runErr != nil {
+			return fmt.Errorf("%s: %w", id, runErr)
+		}
+		adopted, reason := classifyAdoption(output)
+		if !adopted {
+			return fmt.Errorf("%s did not adopt its configuration: %s", id, reason)
+		}
+		fmt.Printf("%s: %s\n", id, reason)
+	}
+	return nil
+}
+
+func adoptionCommand(id string) (string, []string, bool) {
+	switch id {
+	case "codex":
+		return "codex", []string{"exec", "Reply with the single word: ready"}, true
+	case "claude-code":
+		return "claude", []string{"-p", "Reply with the single word: ready"}, true
+	default:
+		return "", nil, false
+	}
+}
+
+func classifyAdoption(output string) (bool, string) {
+	lowered := strings.ToLower(output)
+	for _, marker := range []string{"not logged in", "please run /login", "login required", "authentication required", "api key not found", "missing api key", "unauthorized", "no credentials"} {
+		if strings.Contains(lowered, marker) {
+			return false, "auth/login error (configuration was not adopted)"
+		}
+	}
+	for _, marker := range []string{"provider: oneagent", "reconnecting", "connection refused", "econnrefused", "could not connect", "failed to connect", "fetch failed", "network error", "unreachable", "os error 61", "os error 111"} {
+		if strings.Contains(lowered, marker) {
+			return true, "connection failure (configuration was adopted)"
+		}
+	}
+	return false, "output showed neither a connection failure nor an authentication error"
+}
+
+func newIsolation(root string) (isolation, func(), error) {
+	directory, err := os.MkdirTemp("", "oneagent-rc-")
+	if err != nil {
+		return isolation{}, func() {}, err
+	}
+	home := filepath.Join(directory, "home")
+	prefix := filepath.Join(directory, "npm-prefix")
+	if err := os.MkdirAll(home, 0o700); err != nil {
+		os.RemoveAll(directory)
+		return isolation{}, func() {}, err
+	}
+	pathEntry := filepath.Join(prefix, "bin")
+	if runtime.GOOS == "windows" {
+		pathEntry = prefix
+	}
+	env := make([]string, 0)
+	for _, entry := range os.Environ() {
+		name, _, _ := strings.Cut(entry, "=")
+		upper := strings.ToUpper(name)
+		if strings.Contains(upper, "KEY") || strings.Contains(upper, "TOKEN") || strings.Contains(upper, "SECRET") || strings.Contains(upper, "PASSWORD") {
+			continue
+		}
+		if name == "NPM_CONFIG_USERCONFIG" || name == "npm_config_userconfig" || name == "UV_CONFIG_FILE" {
+			continue
+		}
+		env = append(env, entry)
+	}
+	pathValue := os.Getenv("PATH")
+	env = appendEnv(env, "HOME", home)
+	env = appendEnv(env, "USERPROFILE", home)
+	env = appendEnv(env, "ONEAGENT_HOME", home)
+	env = appendEnv(env, "NPM_CONFIG_PREFIX", prefix)
+	env = appendEnv(env, "npm_config_prefix", prefix)
+	env = appendEnv(env, "NPM_CONFIG_CACHE", filepath.Join(directory, "npm-cache"))
+	env = appendEnv(env, "NPM_CONFIG_USERCONFIG", filepath.Join(directory, "npmrc"))
+	env = appendEnv(env, "PATH", pathEntry+string(os.PathListSeparator)+pathValue)
+	cli, err := findCLI(root)
+	if err != nil {
+		os.RemoveAll(directory)
+		return isolation{}, func() {}, err
+	}
+	return isolation{root: directory, home: home, env: env, cli: cli}, func() { _ = os.RemoveAll(directory) }, nil
+}
+
+func findCLI(root string) (string, error) {
+	if value := os.Getenv("ONEAGENT_CLI_BINARY"); value != "" {
+		if info, err := os.Stat(value); err == nil && !info.IsDir() {
+			return value, nil
+		}
+	}
+	names := []string{"oneagent"}
+	if runtime.GOOS == "windows" {
+		names = append([]string{"oneagent.exe"}, names...)
+	}
+	for _, name := range names {
+		candidate := filepath.Join(root, "bin", name)
+		if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
+			return candidate, nil
+		}
+	}
+	if value, err := exec.LookPath("oneagent"); err == nil {
+		return value, nil
+	}
+	return "", errors.New("build the Go CLI before running the RC checks")
+}
+
+func runCLI(ctx context.Context, isolated isolation, args ...string) (execResult, error) {
+	return runWithEnv(ctx, isolated.env, 15*time.Minute, append([]string{isolated.cli}, args...)...)
+}
+
+type execResult struct {
+	ExitCode int
+	Stdout   string
+	Stderr   string
+}
+
+func runWithEnv(ctx context.Context, env []string, timeout time.Duration, argv ...string) (execResult, error) {
+	if len(argv) == 0 {
+		return execResult{}, errors.New("empty command")
+	}
+	runCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+	command := exec.CommandContext(runCtx, argv[0], argv[1:]...)
+	command.Env = env
+	stdout, stderr := &strings.Builder{}, &strings.Builder{}
+	command.Stdout, command.Stderr = stdout, stderr
+	err := command.Run()
+	result := execResult{Stdout: stdout.String(), Stderr: stderr.String()}
+	if command.ProcessState != nil {
+		result.ExitCode = command.ProcessState.ExitCode()
+	}
+	if runCtx.Err() != nil {
+		return result, runCtx.Err()
+	}
+	if err != nil {
+		if _, ok := errors.AsType[*exec.ExitError](err); ok {
+			return result, nil
+		}
+		return result, err
+	}
+	return result, nil
+}
+
+func commandVersion(ctx context.Context, env []string, executable string, args []string) (string, error) {
+	if len(args) == 0 {
+		args = []string{"--version"}
+	}
+	argv := append([]string{executable}, args...)
+	result, err := runWithEnv(ctx, env, 30*time.Second, argv...)
+	if err != nil {
+		return "", err
+	}
+	if result.ExitCode != 0 {
+		return "", fmt.Errorf("exit code %d: %s", result.ExitCode, compact(result.Stdout+" "+result.Stderr))
+	}
+	value := install.VersionFromOutput(result.Stdout + "\n" + result.Stderr)
+	if value == "" {
+		return "", fmt.Errorf("no semantic version in %q", compact(result.Stdout+" "+result.Stderr))
+	}
+	return value, nil
+}
+
+func lookPath(env []string, command string) (string, bool) {
+	pathValue := ""
+	for _, entry := range env {
+		name, value, ok := strings.Cut(entry, "=")
+		if ok && name == "PATH" {
+			pathValue = value
+			break
+		}
+	}
+	for _, directory := range filepath.SplitList(pathValue) {
+		candidate := filepath.Join(directory, command)
+		if info, err := os.Stat(candidate); err == nil && !info.IsDir() && info.Mode()&0o111 != 0 {
+			return candidate, true
+		}
+		if runtime.GOOS == "windows" {
+			for _, suffix := range []string{".exe", ".cmd", ".bat"} {
+				candidate = filepath.Join(directory, command+suffix)
+				if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
+					return candidate, true
+				}
+			}
+		}
+	}
+	return "", false
+}
+
+func appendEnv(values []string, name, value string) []string {
+	filtered := make([]string, 0, len(values)+1)
+	for _, entry := range values {
+		if key, _, ok := strings.Cut(entry, "="); !ok || key != name {
+			filtered = append(filtered, entry)
+		}
+	}
+	return append(filtered, name+"="+value)
+}
+
+func splitIDs(value string) []string {
+	parts := strings.Split(value, ",")
+	result := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if trimmed := strings.TrimSpace(part); trimmed != "" {
+			result = append(result, trimmed)
+		}
+	}
+	return result
+}
+
+func compact(value string) string {
+	value = strings.Join(strings.Fields(value), " ")
+	if len(value) > 500 {
+		return value[len(value)-500:]
+	}
+	return value
+}
diff --git a/cmd/oneagent-release/main.go b/cmd/oneagent-release/main.go
new file mode 100644
index 00000000..ec43475c
--- /dev/null
+++ b/cmd/oneagent-release/main.go
@@ -0,0 +1,1031 @@
+// Command oneagent-release builds and validates the native Wails distribution.
+// It deliberately uses only the Go and Node toolchains already required by the
+// application; release output never embeds a language runtime.
+package main
+
+import (
+	"archive/zip"
+	"bufio"
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"slices"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	"github.com/MaimoryLab/OneAgent/internal/version"
+)
+
+const previewChannel = "technical-preview-unsigned"
+
+type targetInfo struct {
+	OS   string
+	Arch string
+}
+
+type toolchainInfo struct {
+	Go       string `json:"go"`
+	Wails    string `json:"wails"`
+	Frontend string `json:"frontend"`
+}
+
+type artifactInfo struct {
+	File   string `json:"file"`
+	SHA256 string `json:"sha256"`
+	Bytes  int64  `json:"bytes"`
+}
+
+type releaseManifest struct {
+	SchemaVersion   int               `json:"schema_version"`
+	OneAgentVersion string            `json:"oneagent_version"`
+	Channel         string            `json:"channel"`
+	Unsigned        bool              `json:"unsigned"`
+	Platform        string            `json:"platform"`
+	Arch            string            `json:"arch"`
+	Toolchain       toolchainInfo     `json:"toolchain"`
+	SystemWebView   string            `json:"system_webview"`
+	BuiltAt         string            `json:"built_at"`
+	AgentVersions   map[string]string `json:"agent_versions"`
+	Artifacts       []artifactInfo    `json:"artifacts"`
+}
+
+type packageLock struct {
+	Packages map[string]struct {
+		Version string `json:"version"`
+		License any    `json:"license"`
+		Dev     bool   `json:"dev"`
+	} `json:"packages"`
+}
+
+type moduleInfo struct {
+	Path    string
+	Version string
+	Dir     string
+	Main    bool
+}
+
+var (
+	remoteAssetPattern = regexp.MustCompile(`(?i)(?:src|href)\s*=\s*["']https?://|@import\s+(?:url\()?\s*["']?https?://|url\(\s*["']?https?://`)
+	secretPattern      = regexp.MustCompile(`(?i)sk-[A-Za-z0-9_-]{20,}|Bearer\s+[A-Za-z0-9._-]{24,}`)
+)
+
+func main() { os.Exit(run(os.Args[1:], os.Stdout, os.Stderr)) }
+
+func run(args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		printUsage(stderr)
+		return 2
+	}
+	root, err := repositoryRoot()
+	if err != nil {
+		fmt.Fprintln(stderr, err)
+		return 1
+	}
+	switch args[0] {
+	case "build":
+		if err := buildRelease(root, args[1:], stdout, stderr); err != nil {
+			fmt.Fprintln(stderr, err)
+			return 1
+		}
+		return 0
+	case "check":
+		if err := checkRelease(commandPath(args[1:])); err != nil {
+			fmt.Fprintln(stderr, err)
+			return 1
+		}
+		fmt.Fprintln(stdout, "release policy checks passed")
+		return 0
+	default:
+		printUsage(stderr)
+		return 2
+	}
+}
+
+func printUsage(w io.Writer) {
+	fmt.Fprintln(w, "usage: oneagent-release build [--source] [--skip-frontend] [--channel technical-preview-unsigned]")
+	fmt.Fprintln(w, "       oneagent-release check [release-directory]")
+}
+
+func commandPath(args []string) string {
+	if len(args) == 0 || strings.TrimSpace(args[0]) == "" {
+		return "release"
+	}
+	return args[0]
+}
+
+func repositoryRoot() (string, error) {
+	directory, err := os.Getwd()
+	if err != nil {
+		return "", err
+	}
+	for {
+		if _, err := os.Stat(filepath.Join(directory, "go.mod")); err == nil {
+			return directory, nil
+		}
+		parent := filepath.Dir(directory)
+		if parent == directory {
+			return "", errors.New("could not locate the OneAgent repository root")
+		}
+		directory = parent
+	}
+}
+
+func buildRelease(root string, args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("build", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	channel := flags.String("channel", previewChannel, "release channel")
+	source := flags.Bool("source", false, "also create a source archive")
+	skipFrontend := flags.Bool("skip-frontend", false, "use an existing frontend/dist")
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+	if *channel != previewChannel {
+		return fmt.Errorf("only %q is publishable while Wails is Alpha", previewChannel)
+	}
+	target := currentTarget()
+	if err := ensureFrontend(root, *skipFrontend); err != nil {
+		return err
+	}
+	metadata := filepath.Join(root, "build", "metadata")
+	if err := os.RemoveAll(metadata); err != nil {
+		return fmt.Errorf("clear release metadata: %w", err)
+	}
+	if err := generateNotices(root, metadata); err != nil {
+		return err
+	}
+	stage, err := buildBinaries(root, target, metadata)
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Join(root, "release"), 0o755); err != nil {
+		return err
+	}
+	artifactName := fmt.Sprintf("OneAgent-%s-%s-%s-%s.zip", version.Version, *channel, target.OS, target.Arch)
+	artifactPath := filepath.Join(root, "release", artifactName)
+	if err := zipDirectory(stage, artifactPath, "OneAgent"); err != nil {
+		return fmt.Errorf("create release archive: %w", err)
+	}
+	artifacts := []string{artifactPath}
+	if *source {
+		sourcePath := filepath.Join(root, fmt.Sprintf("release/OneAgent-%s-source.zip", version.Version))
+		if err := zipSource(root, metadata, sourcePath, version.Version); err != nil {
+			return fmt.Errorf("create source archive: %w", err)
+		}
+		artifacts = append(artifacts, sourcePath)
+	}
+	manifestPath := filepath.Join(root, fmt.Sprintf("release/release-manifest-%s-%s.json", target.OS, target.Arch))
+	manifest, err := makeManifest(root, target, *channel, artifacts)
+	if err != nil {
+		return err
+	}
+	manifestData, err := json.MarshalIndent(manifest, "", "  ")
+	if err != nil {
+		return err
+	}
+	manifestData = append(manifestData, '\n')
+	if err := os.WriteFile(manifestPath, manifestData, 0o644); err != nil {
+		return fmt.Errorf("write release manifest: %w", err)
+	}
+	checksumPath := filepath.Join(root, fmt.Sprintf("release/SHA256SUMS-%s-%s.txt", target.OS, target.Arch))
+	if err := writeChecksums(checksumPath, append(artifacts, manifestPath)); err != nil {
+		return err
+	}
+	fmt.Fprintln(stdout, artifactPath)
+	return nil
+}
+
+func currentTarget() targetInfo {
+	osID := "linux"
+	switch runtime.GOOS {
+	case "darwin":
+		osID = "macos"
+	case "windows":
+		osID = "windows"
+	}
+	arch := "x64"
+	if runtime.GOARCH == "arm64" {
+		arch = "arm64"
+	}
+	return targetInfo{OS: osID, Arch: arch}
+}
+
+func ensureFrontend(root string, skip bool) error {
+	dist := filepath.Join(root, "frontend", "dist")
+	if !skip {
+		npm, err := exec.LookPath("npm")
+		if err != nil {
+			return errors.New("npm is required to build the React frontend")
+		}
+		if err := runCommand(root, npm, "run", "build"); err != nil {
+			return fmt.Errorf("build frontend: %w", err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(dist, "index.html")); err != nil {
+		return errors.New("frontend/dist/index.html is missing; build the frontend first")
+	}
+	var maps []string
+	if err := filepath.WalkDir(dist, func(path string, entry os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if !entry.IsDir() && strings.HasSuffix(strings.ToLower(path), ".map") {
+			maps = append(maps, path)
+		}
+		return nil
+	}); err != nil {
+		return err
+	}
+	if len(maps) > 0 {
+		return fmt.Errorf("source maps are forbidden in release assets: %s", maps[0])
+	}
+	return nil
+}
+
+func buildBinaries(root string, target targetInfo, metadata string) (string, error) {
+	stage := filepath.Join(root, "build", "release-stage", target.OS+"-"+target.Arch)
+	if err := os.RemoveAll(stage); err != nil {
+		return "", err
+	}
+	oneDir := filepath.Join(stage, "OneAgent")
+	if err := os.MkdirAll(oneDir, 0o755); err != nil {
+		return "", err
+	}
+	goTool, err := exec.LookPath("go")
+	if err != nil {
+		return "", errors.New("go is required to build the release")
+	}
+	desktop := filepath.Join(oneDir, "OneAgent")
+	desktopTags := "wails,production"
+	if target.OS == "linux" {
+		desktopTags += ",gtk3"
+	}
+	if target.OS == "macos" {
+		appDir := filepath.Join(oneDir, "OneAgent.app", "Contents", "MacOS")
+		if err := os.MkdirAll(appDir, 0o755); err != nil {
+			return "", err
+		}
+		desktop = filepath.Join(appDir, "OneAgent")
+	}
+	ldflags := "-w -s"
+	if target.OS == "windows" {
+		desktop = filepath.Join(oneDir, "OneAgent.exe")
+		ldflags += " -H windowsgui"
+	}
+	if err := runCommand(root, goTool, "build", "-tags", desktopTags, "-trimpath", "-buildvcs=false", "-ldflags="+ldflags, "-o", desktop, "./cmd/oneagent-desktop"); err != nil {
+		return "", fmt.Errorf("build desktop binary: %w", err)
+	}
+	cliName := "oneagent"
+	if target.OS == "windows" {
+		cliName += ".exe"
+	}
+	if err := runCommand(root, goTool, "build", "-trimpath", "-buildvcs=false", "-ldflags=-w -s", "-o", filepath.Join(oneDir, cliName), "./cmd/oneagent"); err != nil {
+		return "", fmt.Errorf("build CLI binary: %w", err)
+	}
+	if target.OS == "macos" {
+		plist := `<?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>CFBundleDisplayName</key><string>OneAgent</string>
+<key>CFBundleExecutable</key><string>OneAgent</string>
+<key>CFBundleIdentifier</key><string>com.maimorylab.oneagent</string>
+<key>CFBundleName</key><string>OneAgent</string>
+<key>CFBundlePackageType</key><string>APPL</string>
+<key>CFBundleShortVersionString</key><string>0.3.0</string>
+<key>CFBundleVersion</key><string>1</string>
+</dict></plist>
+`
+		if err := os.WriteFile(filepath.Join(oneDir, "OneAgent.app", "Contents", "Info.plist"), []byte(plist), 0o644); err != nil {
+			return "", err
+		}
+	}
+	if err := copyFile(filepath.Join(root, "README.md"), filepath.Join(oneDir, "README.md")); err != nil {
+		return "", err
+	}
+	// Both locks ship so a reviewer can audit what the app would download —
+	// Agent packages and the runtimes that install them — without unpacking the
+	// binary.
+	for _, lock := range []string{"agents.lock.json", "runtimes.lock.json"} {
+		if err := copyFile(filepath.Join(root, lock), filepath.Join(oneDir, lock)); err != nil {
+			return "", err
+		}
+	}
+	if err := copyFile(filepath.Join(metadata, "THIRD_PARTY_NOTICES.md"), filepath.Join(oneDir, "THIRD_PARTY_NOTICES.md")); err != nil {
+		return "", err
+	}
+	if err := copyDir(filepath.Join(metadata, "licenses"), filepath.Join(oneDir, "licenses")); err != nil {
+		return "", err
+	}
+	return stage, nil
+}
+
+func runCommand(dir, executable string, args ...string) error {
+	command := exec.Command(executable, args...)
+	command.Dir = dir
+	command.Stdout = os.Stdout
+	command.Stderr = os.Stderr
+	return command.Run()
+}
+
+func makeManifest(root string, target targetInfo, channel string, files []string) (releaseManifest, error) {
+	lock, err := catalog.LoadEmbedded()
+	if err != nil {
+		return releaseManifest{}, err
+	}
+	frontendVersion := "unknown"
+	if data, readErr := os.ReadFile(filepath.Join(root, "frontend", "package.json")); readErr == nil {
+		var packageJSON struct {
+			Version string `json:"version"`
+		}
+		if json.Unmarshal(data, &packageJSON) == nil && packageJSON.Version != "" {
+			frontendVersion = packageJSON.Version
+		}
+	}
+	tools := readToolVersions(filepath.Join(root, "build", "tool-versions.env"))
+	agentVersions := make(map[string]string)
+	for id, agent := range lock.Agents {
+		if agent.Package != nil {
+			agentVersions[id] = agent.Package.Version
+		}
+	}
+	artifacts := make([]artifactInfo, 0, len(files))
+	for _, file := range files {
+		info, err := os.Stat(file)
+		if err != nil {
+			return releaseManifest{}, err
+		}
+		digest, err := fileSHA256(file)
+		if err != nil {
+			return releaseManifest{}, err
+		}
+		artifacts = append(artifacts, artifactInfo{File: filepath.Base(file), SHA256: digest, Bytes: info.Size()})
+	}
+	sort.Slice(artifacts, func(i, j int) bool { return artifacts[i].File < artifacts[j].File })
+	return releaseManifest{
+		SchemaVersion: 2, OneAgentVersion: version.Version, Channel: channel,
+		Unsigned: true, Platform: target.OS, Arch: target.Arch,
+		Toolchain:     toolchainInfo{Go: runtime.Version(), Wails: tools["WAILS_VERSION"], Frontend: frontendVersion},
+		SystemWebView: webViewRequirement(target.OS), BuiltAt: time.Now().UTC().Format(time.RFC3339),
+		AgentVersions: agentVersions, Artifacts: artifacts,
+	}, nil
+}
+
+func readToolVersions(file string) map[string]string {
+	values := map[string]string{}
+	data, err := os.ReadFile(file)
+	if err != nil {
+		return values
+	}
+	for line := range strings.SplitSeq(string(data), "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		if key, value, ok := strings.Cut(line, "="); ok {
+			values[strings.TrimSpace(key)] = strings.TrimSpace(value)
+		}
+	}
+	return values
+}
+
+func webViewRequirement(osID string) string {
+	switch osID {
+	case "macos":
+		return "WKWebView (macOS 12+)"
+	case "windows":
+		return "WebView2 Runtime"
+	default:
+		return "GTK3 + WebKitGTK 4.1"
+	}
+}
+
+func writeChecksums(file string, paths []string) error {
+	sort.Slice(paths, func(i, j int) bool { return filepath.Base(paths[i]) < filepath.Base(paths[j]) })
+	var builder strings.Builder
+	for _, path := range paths {
+		digest, err := fileSHA256(path)
+		if err != nil {
+			return err
+		}
+		fmt.Fprintf(&builder, "%s  %s\n", digest, filepath.Base(path))
+	}
+	return os.WriteFile(file, []byte(builder.String()), 0o644)
+}
+
+func fileSHA256(file string) (string, error) {
+	hash := sha256.New()
+	handle, err := os.Open(file)
+	if err != nil {
+		return "", err
+	}
+	defer handle.Close()
+	if _, err := io.Copy(hash, handle); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(hash.Sum(nil)), nil
+}
+
+func zipDirectory(source, destination, rootName string) error {
+	return createZip(destination, func(writer *zip.Writer) error {
+		return filepath.WalkDir(source, func(file string, entry os.DirEntry, err error) error {
+			if err != nil {
+				return err
+			}
+			if entry.IsDir() {
+				return nil
+			}
+			relative, err := filepath.Rel(source, file)
+			if err != nil {
+				return err
+			}
+			return addZipFile(writer, file, path.Join(rootName, filepath.ToSlash(relative)))
+		})
+	})
+}
+
+func zipSource(root, metadata, destination, versionValue string) error {
+	return createZip(destination, func(writer *zip.Writer) error {
+		command := exec.Command("git", "ls-files", "-co", "--exclude-standard", "-z")
+		command.Dir = root
+		output, err := command.Output()
+		if err != nil {
+			return fmt.Errorf("list source files: %w", err)
+		}
+		files := strings.SplitSeq(string(output), "\x00")
+		for relative := range files {
+			if relative == "" {
+				continue
+			}
+			if sourceArchiveExcluded(relative) {
+				continue
+			}
+			file := filepath.Join(root, filepath.FromSlash(relative))
+			if info, statErr := os.Stat(file); statErr == nil && info.Mode().IsRegular() {
+				if err := addZipFile(writer, file, path.Join("OneAgent-"+versionValue, filepath.ToSlash(relative))); err != nil {
+					return err
+				}
+			}
+		}
+		for _, relative := range []string{"THIRD_PARTY_NOTICES.md", "licenses"} {
+			file := filepath.Join(metadata, relative)
+			if info, statErr := os.Stat(file); statErr == nil {
+				if info.IsDir() {
+					if err := addZipTree(writer, file, path.Join("OneAgent-"+versionValue, relative)); err != nil {
+						return err
+					}
+				} else if err := addZipFile(writer, file, path.Join("OneAgent-"+versionValue, relative)); err != nil {
+					return err
+				}
+			}
+		}
+		return nil
+	})
+}
+
+func sourceArchiveExcluded(relative string) bool {
+	relative = filepath.ToSlash(relative)
+	for _, prefix := range []string{"build/metadata/", "build/release-stage/", "release/", "frontend/dist/"} {
+		if strings.HasPrefix(relative, prefix) {
+			return true
+		}
+	}
+	return false
+}
+
+func createZip(destination string, fill func(*zip.Writer) error) error {
+	if err := os.MkdirAll(filepath.Dir(destination), 0o755); err != nil {
+		return err
+	}
+	file, err := os.Create(destination)
+	if err != nil {
+		return err
+	}
+	writer := zip.NewWriter(file)
+	fillErr := fill(writer)
+	closeErr := writer.Close()
+	fileCloseErr := file.Close()
+	if fillErr != nil {
+		return fillErr
+	}
+	if closeErr != nil {
+		return closeErr
+	}
+	return fileCloseErr
+}
+
+func addZipTree(writer *zip.Writer, source, rootName string) error {
+	return filepath.WalkDir(source, func(file string, entry os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if entry.IsDir() {
+			return nil
+		}
+		relative, err := filepath.Rel(source, file)
+		if err != nil {
+			return err
+		}
+		return addZipFile(writer, file, path.Join(rootName, filepath.ToSlash(relative)))
+	})
+}
+
+func addZipFile(writer *zip.Writer, file, name string) error {
+	info, err := os.Stat(file)
+	if err != nil {
+		return err
+	}
+	header, err := zip.FileInfoHeader(info)
+	if err != nil {
+		return err
+	}
+	header.Name = filepath.ToSlash(name)
+	header.Method = zip.Deflate
+	header.SetModTime(time.Date(1980, 1, 1, 0, 0, 0, 0, time.UTC))
+	entry, err := writer.CreateHeader(header)
+	if err != nil {
+		return err
+	}
+	input, err := os.Open(file)
+	if err != nil {
+		return err
+	}
+	defer input.Close()
+	_, err = io.Copy(entry, input)
+	return err
+}
+
+func copyFile(source, destination string) error {
+	data, err := os.ReadFile(source)
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(destination), 0o755); err != nil {
+		return err
+	}
+	return os.WriteFile(destination, data, 0o644)
+}
+
+func copyDir(source, destination string) error {
+	if _, err := os.Stat(source); os.IsNotExist(err) {
+		return os.MkdirAll(destination, 0o755)
+	}
+	return filepath.WalkDir(source, func(file string, entry os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		relative, err := filepath.Rel(source, file)
+		if err != nil {
+			return err
+		}
+		target := filepath.Join(destination, relative)
+		if entry.IsDir() {
+			return os.MkdirAll(target, 0o755)
+		}
+		return copyFile(file, target)
+	})
+}
+
+func generateNotices(root, output string) error {
+	if err := os.MkdirAll(filepath.Join(output, "licenses"), 0o755); err != nil {
+		return err
+	}
+	goPackages, err := goPackages(root)
+	if err != nil {
+		return err
+	}
+	frontendPackages, err := frontendPackages(root, filepath.Join(output, "licenses"))
+	if err != nil {
+		return err
+	}
+	manifest, err := catalog.LoadEmbedded()
+	if err != nil {
+		return err
+	}
+	runtimes, err := catalog.LoadEmbeddedRuntimes()
+	if err != nil {
+		return err
+	}
+	var builder strings.Builder
+	builder.WriteString("# OneAgent Third-Party Notices\n\n")
+	builder.WriteString("OneAgent bundles the Go application and its built React assets. Agent packages are not bundled; they are installed from the listed upstream source only after user confirmation.\n\n")
+	builder.WriteString("## Runtime Components\n\n")
+	builder.WriteString("- Go standard library: BSD-3-Clause, https://go.dev/LICENSE\n")
+	builder.WriteString("- Wails and Go modules: see the bundled `licenses/` files and module source URLs below.\n\n")
+	builder.WriteString("| Go module | Version | License file | Source |\n| --- | --- | --- | --- |\n")
+	for _, item := range goPackages {
+		fmt.Fprintf(&builder, "| `%s` | `%s` | `%s` | https://pkg.go.dev/%s@%s |\n", item.Name, item.Version, item.License, item.Name, item.Version)
+	}
+	builder.WriteString("\n## Frontend Runtime Packages\n\n| Package | Version | License | License file |\n| --- | --- | --- | --- |\n")
+	for _, item := range frontendPackages {
+		fmt.Fprintf(&builder, "| `%s` | `%s` | %s | %s |\n", item.Name, item.Version, item.License, item.LicenseFile)
+	}
+	builder.WriteString("\n## Agent Installation Targets (Not Bundled)\n\n| Agent | Locked package | License | Source | License reference |\n| --- | --- | --- | --- | --- |\n")
+	// Iterate in catalog order: a map walk would reorder the table on every run
+	// and change the notice file's own SHA-256.
+	for _, id := range catalog.AgentIDs(manifest) {
+		agent := manifest.Agents[id]
+		if agent.Package == nil {
+			continue
+		}
+		fmt.Fprintf(&builder, "| %s | `%s@%s` | %s | %s | %s |\n", agent.Name, agent.Package.Name, agent.Package.Version, agent.Package.License, agent.Package.Source, agent.Package.LicenseURL)
+	}
+	builder.WriteString("\n## Runtime Bootstrap Targets (Not Bundled)\n\nOneAgent can download these runtimes on request to provide the package managers Agents are installed with. Each download is pinned to the version and SHA-256 in `runtimes.lock.json` and is verified before use.\n\n| Runtime | Locked version | License | Source | License reference |\n| --- | --- | --- | --- | --- |\n")
+	for _, id := range runtimes.RuntimeOrder {
+		entry := runtimes.Runtimes[id]
+		fmt.Fprintf(&builder, "| %s | `%s` | %s | %s | %s |\n", entry.Name, entry.Version, entry.License, entry.Source, entry.LicenseURL)
+	}
+	return os.WriteFile(filepath.Join(output, "THIRD_PARTY_NOTICES.md"), []byte(builder.String()), 0o644)
+}
+
+type noticeItem struct {
+	Name        string
+	Version     string
+	License     string
+	LicenseFile string
+}
+
+func goPackages(root string) ([]noticeItem, error) {
+	command := exec.Command("go", "list", "-m", "-json", "all")
+	command.Dir = root
+	output, err := command.Output()
+	if err != nil {
+		return nil, fmt.Errorf("list Go modules: %w", err)
+	}
+	decoder := json.NewDecoder(bytes.NewReader(output))
+	items := []noticeItem{}
+	for {
+		var module moduleInfo
+		if err := decoder.Decode(&module); errors.Is(err, io.EOF) {
+			break
+		} else if err != nil {
+			return nil, fmt.Errorf("decode Go module list: %w", err)
+		}
+		if module.Main || module.Path == "" {
+			continue
+		}
+		license := "see bundled source"
+		licenseFile := ""
+		if module.Dir != "" {
+			licenseFile = copyLicense(module.Dir, filepath.Join(root, "build", "metadata", "licenses"), "go-"+module.Path)
+		}
+		if licenseFile != "" {
+			license = licenseFile
+		}
+		items = append(items, noticeItem{Name: module.Path, Version: module.Version, License: license, LicenseFile: licenseFile})
+	}
+	sort.Slice(items, func(i, j int) bool { return items[i].Name < items[j].Name })
+	return items, nil
+}
+
+func frontendPackages(root, licenseDir string) ([]noticeItem, error) {
+	data, err := os.ReadFile(filepath.Join(root, "frontend", "package-lock.json"))
+	if err != nil {
+		return nil, err
+	}
+	var lock packageLock
+	if err := json.Unmarshal(data, &lock); err != nil {
+		return nil, fmt.Errorf("read frontend lock: %w", err)
+	}
+	items := []noticeItem{}
+	for relative, metadata := range lock.Packages {
+		if !strings.HasPrefix(relative, "node_modules/") || metadata.Dev || metadata.Version == "" {
+			continue
+		}
+		name := strings.TrimPrefix(relative, "node_modules/")
+		license := licenseValue(metadata.License)
+		licenseFile := ""
+		packageDir := filepath.Join(root, "frontend", relative)
+		if packageData, readErr := os.ReadFile(filepath.Join(packageDir, "package.json")); readErr == nil {
+			var packageJSON struct {
+				Name    string `json:"name"`
+				License any    `json:"license"`
+			}
+			if json.Unmarshal(packageData, &packageJSON) == nil {
+				if packageJSON.Name != "" {
+					name = packageJSON.Name
+				}
+				if packageJSON.License != nil {
+					license = licenseValue(packageJSON.License)
+				}
+			}
+		}
+		if copied := copyLicense(packageDir, licenseDir, "npm-"+name+"-"+metadata.Version); copied != "" {
+			licenseFile = copied
+		}
+		if license == "" {
+			license = "see package metadata"
+		}
+		if licenseFile == "" {
+			licenseFile = "not provided by package"
+		}
+		items = append(items, noticeItem{Name: name, Version: metadata.Version, License: license, LicenseFile: licenseFile})
+	}
+	sort.Slice(items, func(i, j int) bool { return items[i].Name < items[j].Name })
+	return items, nil
+}
+
+func licenseValue(value any) string {
+	switch typed := value.(type) {
+	case string:
+		return typed
+	case map[string]any:
+		if name, ok := typed["type"].(string); ok {
+			return name
+		}
+		if name, ok := typed["name"].(string); ok {
+			return name
+		}
+	case []any:
+		parts := make([]string, 0, len(typed))
+		for _, item := range typed {
+			if value := licenseValue(item); value != "" {
+				parts = append(parts, value)
+			}
+		}
+		return strings.Join(parts, ", ")
+	}
+	return ""
+}
+
+func copyLicense(source, destination, label string) string {
+	entries, err := os.ReadDir(source)
+	if err != nil {
+		return ""
+	}
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+		lower := strings.ToLower(entry.Name())
+		if !(strings.HasPrefix(lower, "license") || strings.HasPrefix(lower, "licence") || strings.HasPrefix(lower, "copying") || strings.HasPrefix(lower, "notice")) {
+			continue
+		}
+		if err := os.MkdirAll(destination, 0o755); err != nil {
+			return ""
+		}
+		name := safeName(label) + filepath.Ext(entry.Name())
+		if err := copyFile(filepath.Join(source, entry.Name()), filepath.Join(destination, name)); err != nil {
+			return ""
+		}
+		return filepath.ToSlash(filepath.Join("licenses", name))
+	}
+	return ""
+}
+
+func safeName(value string) string {
+	var builder strings.Builder
+	for _, character := range value {
+		if (character >= 'a' && character <= 'z') || (character >= 'A' && character <= 'Z') || (character >= '0' && character <= '9') || character == '.' || character == '-' || character == '_' {
+			builder.WriteRune(character)
+		} else {
+			builder.WriteByte('_')
+		}
+	}
+	return strings.Trim(builder.String(), "_")
+}
+
+func checkRelease(directory string) error {
+	manifests, _ := filepath.Glob(filepath.Join(directory, "release-manifest-*.json"))
+	archives, _ := filepath.Glob(filepath.Join(directory, "OneAgent-*.zip"))
+	problems := []string{}
+	if len(manifests) == 0 {
+		problems = append(problems, "release manifest is missing")
+	}
+	if len(archives) == 0 {
+		problems = append(problems, "release archive is missing")
+	}
+	for _, manifest := range manifests {
+		problems = append(problems, validateManifest(manifest)...)
+	}
+	for _, archive := range archives {
+		problems = append(problems, inspectArchive(archive)...)
+	}
+	if len(problems) > 0 {
+		return errors.New(strings.Join(problems, "\n"))
+	}
+	return nil
+}
+
+func validateManifest(file string) []string {
+	problems := []string{}
+	data, err := os.ReadFile(file)
+	if err != nil {
+		return []string{fmt.Sprintf("read manifest %s: %v", filepath.Base(file), err)}
+	}
+	var manifest releaseManifest
+	var raw map[string]any
+	if err := json.Unmarshal(data, &manifest); err != nil || json.Unmarshal(data, &raw) != nil {
+		return []string{fmt.Sprintf("invalid release manifest %s", filepath.Base(file))}
+	}
+	if manifest.SchemaVersion != 2 {
+		problems = append(problems, "unsupported release manifest schema: "+filepath.Base(file))
+	}
+	if _, present := raw["python"]; present {
+		problems = append(problems, "release manifest contains a removed python field: "+filepath.Base(file))
+	}
+	if manifest.Channel != previewChannel || !manifest.Unsigned {
+		problems = append(problems, "release manifest must be an unsigned technical preview: "+filepath.Base(file))
+	}
+	if manifest.Toolchain.Go == "" || manifest.Toolchain.Wails == "" || manifest.Toolchain.Frontend == "" || manifest.SystemWebView == "" {
+		problems = append(problems, "release manifest toolchain or WebView requirement is incomplete: "+filepath.Base(file))
+	}
+	if len(manifest.Artifacts) == 0 {
+		return append(problems, "artifact list is missing: "+filepath.Base(file))
+	}
+	expectedVersions := manifest.AgentVersions
+	for _, artifact := range manifest.Artifacts {
+		if filepath.Base(artifact.File) != artifact.File {
+			problems = append(problems, "artifact filename contains a path: "+artifact.File)
+			continue
+		}
+		artifactPath := filepath.Join(filepath.Dir(file), artifact.File)
+		info, statErr := os.Stat(artifactPath)
+		if statErr != nil {
+			problems = append(problems, "manifest artifact is missing: "+artifact.File)
+			continue
+		}
+		if info.Size() != artifact.Bytes {
+			problems = append(problems, "artifact size mismatch: "+artifact.File)
+		}
+		if digest, hashErr := fileSHA256(artifactPath); hashErr != nil || digest != artifact.SHA256 {
+			problems = append(problems, "artifact checksum mismatch: "+artifact.File)
+		}
+		if !strings.Contains(artifact.File, "-source.zip") && !strings.Contains(artifact.File, manifest.Channel) {
+			problems = append(problems, "artifact channel mismatch: "+artifact.File)
+		}
+		if versions := archiveAgentVersions(artifactPath); versions == nil {
+			problems = append(problems, "lock manifest is missing or invalid: "+artifact.File)
+		} else if !mapsEqual(versions, expectedVersions) {
+			problems = append(problems, "locked Agent versions mismatch: "+artifact.File)
+		}
+	}
+	suffix := strings.TrimSuffix(strings.TrimPrefix(filepath.Base(file), "release-manifest-"), ".json")
+	checksumFile := filepath.Join(filepath.Dir(file), "SHA256SUMS-"+suffix+".txt")
+	checksums := map[string]string{}
+	if checksumData, readErr := os.ReadFile(checksumFile); readErr != nil {
+		problems = append(problems, "checksum file is missing: "+filepath.Base(checksumFile))
+	} else {
+		scanner := bufio.NewScanner(bytes.NewReader(checksumData))
+		for scanner.Scan() {
+			fields := strings.Fields(scanner.Text())
+			if len(fields) != 2 || len(fields[0]) != sha256.Size*2 {
+				problems = append(problems, "invalid checksum line in "+filepath.Base(checksumFile))
+				continue
+			}
+			checksums[fields[1]] = fields[0]
+		}
+		for _, expected := range append([]string{filepath.Base(file)}, artifactNames(manifest.Artifacts)...) {
+			candidate := filepath.Join(filepath.Dir(file), expected)
+			if digest, hashErr := fileSHA256(candidate); hashErr == nil && checksums[expected] != digest {
+				problems = append(problems, "checksum file mismatch: "+expected)
+			}
+		}
+	}
+	return problems
+}
+
+func artifactNames(artifacts []artifactInfo) []string {
+	names := make([]string, 0, len(artifacts))
+	for _, artifact := range artifacts {
+		names = append(names, artifact.File)
+	}
+	return names
+}
+
+func archiveAgentVersions(file string) map[string]string {
+	archive, err := zip.OpenReader(file)
+	if err != nil {
+		return nil
+	}
+	defer archive.Close()
+	var matches []*zip.File
+	for _, entry := range archive.File {
+		if path.Base(entry.Name) == "agents.lock.json" {
+			matches = append(matches, entry)
+		}
+	}
+	if len(matches) != 1 {
+		return nil
+	}
+	reader, err := matches[0].Open()
+	if err != nil {
+		return nil
+	}
+	defer reader.Close()
+	var manifest struct {
+		Agents map[string]struct {
+			Package *struct {
+				Version string `json:"version"`
+			} `json:"package"`
+		} `json:"agents"`
+	}
+	if json.NewDecoder(reader).Decode(&manifest) != nil {
+		return nil
+	}
+	result := map[string]string{}
+	for id, agent := range manifest.Agents {
+		if agent.Package != nil {
+			result[id] = agent.Package.Version
+		}
+	}
+	return result
+}
+
+func mapsEqual(left, right map[string]string) bool {
+	if len(left) != len(right) {
+		return false
+	}
+	for key, value := range left {
+		if right[key] != value {
+			return false
+		}
+	}
+	return true
+}
+
+func inspectArchive(file string) []string {
+	problems := []string{}
+	archive, err := zip.OpenReader(file)
+	if err != nil {
+		return []string{fmt.Sprintf("cannot open %s: %v", filepath.Base(file), err)}
+	}
+	defer archive.Close()
+	required := map[string]bool{}
+	for _, entry := range archive.File {
+		name := filepath.ToSlash(entry.Name)
+		base := strings.ToLower(path.Base(name))
+		parts := strings.Split(name, "/")
+		if strings.HasPrefix(name, "/") || slicesContain(parts, "..") {
+			problems = append(problems, "unsafe archive path in "+filepath.Base(file)+": "+name)
+		}
+		if strings.EqualFold(base, "agents.lock.json") {
+			required["agents.lock.json"] = true
+		}
+		if strings.EqualFold(base, "runtimes.lock.json") {
+			required["runtimes.lock.json"] = true
+		}
+		if strings.EqualFold(base, "THIRD_PARTY_NOTICES.md") {
+			required["THIRD_PARTY_NOTICES.md"] = true
+		}
+		lowerName := strings.ToLower(name)
+		for _, suffix := range []string{".py", ".pyc", ".pyo", ".pyd", ".whl"} {
+			if strings.HasSuffix(lowerName, suffix) {
+				problems = append(problems, "Python artifact in "+filepath.Base(file)+": "+name)
+			}
+		}
+		if strings.Contains(lowerName, "pyinstaller") || strings.Contains(base, "libpython") {
+			problems = append(problems, "Python runtime in "+filepath.Base(file)+": "+name)
+		}
+		if strings.HasSuffix(lowerName, ".map") {
+			problems = append(problems, "source map in "+filepath.Base(file)+": "+name)
+		}
+		if slicesContain([]string{"codex", "codex.exe", "claude", "claude.exe", "opencode", "opencode.exe", "kilo", "kilo.exe", "aider", "aider.exe"}, base) {
+			problems = append(problems, "Agent binary in "+filepath.Base(file)+": "+name)
+		}
+		if !entry.FileInfo().IsDir() && isTextArchiveFile(lowerName) {
+			reader, openErr := entry.Open()
+			if openErr != nil {
+				continue
+			}
+			data, readErr := io.ReadAll(io.LimitReader(reader, 8<<20))
+			reader.Close()
+			if readErr == nil && secretPattern.Match(data) {
+				problems = append(problems, "possible secret in "+filepath.Base(file)+": "+name)
+			}
+			if readErr == nil && strings.Contains(lowerName, "/frontend/dist/") && remoteAssetPattern.Match(data) {
+				problems = append(problems, "remote asset reference in "+filepath.Base(file)+": "+name)
+			}
+		}
+	}
+	for _, name := range []string{"agents.lock.json", "runtimes.lock.json", "THIRD_PARTY_NOTICES.md"} {
+		if !required[name] {
+			problems = append(problems, "missing "+name+" in "+filepath.Base(file))
+		}
+	}
+	return problems
+}
+
+func isTextArchiveFile(name string) bool {
+	for _, suffix := range []string{".html", ".css", ".js", ".json", ".md", ".txt", ".toml", ".ps1", ".sh"} {
+		if strings.HasSuffix(name, suffix) {
+			return true
+		}
+	}
+	return false
+}
+
+func slicesContain(values []string, target string) bool {
+	return slices.Contains(values, target)
+}
diff --git a/cmd/oneagent/main.go b/cmd/oneagent/main.go
new file mode 100644
index 00000000..20a0c967
--- /dev/null
+++ b/cmd/oneagent/main.go
@@ -0,0 +1,442 @@
+package main
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"os/signal"
+	"runtime"
+	"sort"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/app"
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+	profileStore "github.com/MaimoryLab/OneAgent/internal/profile"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+	"github.com/MaimoryLab/OneAgent/internal/version"
+)
+
+func main() {
+	os.Exit(run(os.Args[1:], os.Stdout, os.Stderr))
+}
+
+func run(args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 || helpRequested(args) {
+		printUsage(stdout)
+		return 0
+	}
+	switch args[0] {
+	case "--version", "-version", "version":
+		_, _ = fmt.Fprintln(stdout, version.Version)
+		return 0
+	case "status":
+		return runStatus(args[1:], stdout, stderr)
+	case "agent":
+		return runAgent(args[1:], stdout, stderr)
+	default:
+		return runInstall(args, stdout, stderr)
+	}
+}
+
+func runStatus(args []string, stdout, stderr io.Writer) int {
+	flags := flag.NewFlagSet("status", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	jsonOutput := flags.Bool("json", false, "write JSON")
+	home := flags.String("home", "", "override the home directory")
+	if err := flags.Parse(args); err != nil {
+		return oneerrors.ExitCodes[oneerrors.InvalidRequest]
+	}
+	info := platform.Current()
+	core := app.NewUseCases(app.StatusOptions{Home: *home, Platform: info})
+	ctx, stop := flagsContext()
+	defer stop()
+	status, err := core.GetStatus(ctx)
+	if err != nil {
+		return writeError(stdout, stderr, err, *jsonOutput, "")
+	}
+	return writeValue(stdout, status, *jsonOutput)
+}
+
+func runAgent(args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		args = []string{"list"}
+	}
+	switch args[0] {
+	case "list":
+		flags := flag.NewFlagSet("agent list", flag.ContinueOnError)
+		flags.SetOutput(stderr)
+		jsonOutput := flags.Bool("json", false, "write JSON")
+		home := flags.String("home", "", "override the home directory")
+		if err := flags.Parse(args[1:]); err != nil {
+			return oneerrors.ExitCodes[oneerrors.InvalidRequest]
+		}
+		core := newCLIUseCases(*home)
+		ctx, stop := flagsContext()
+		defer stop()
+		bindings, err := core.ListAgentBindings(ctx)
+		if err != nil {
+			return writeError(stdout, stderr, err, *jsonOutput, "")
+		}
+		if *jsonOutput {
+			return writeJSON(stdout, map[string]any{"ok": true, "agents": bindings})
+		}
+		if len(bindings) == 0 {
+			_, _ = fmt.Fprintln(stdout, "[oneagent] no Agent has been configured yet")
+			return 0
+		}
+		for _, agentID := range sortedBindingIDs(bindings) {
+			binding := bindings[agentID]
+			_, _ = fmt.Fprintf(stdout, "%-14s %-10s %s\n", agentID, binding.Provider, binding.Model)
+		}
+		return 0
+	case "set":
+		if len(args) < 2 || strings.TrimSpace(args[1]) == "" {
+			return writeError(stdout, stderr, oneerrors.New(oneerrors.InvalidRequest, "agent_id is required"), false, "")
+		}
+		flags := flag.NewFlagSet("agent set", flag.ContinueOnError)
+		flags.SetOutput(stderr)
+		providerID := flags.String("provider", "ppio", "Provider ID")
+		baseURL := flags.String("api-base-url", "", "custom Provider base URL")
+		apiKey := flags.String("api-key", "", "API key")
+		model := flags.String("model", "", "model ID")
+		profileID := flags.String("profile", "", "reuse a saved profile key")
+		smallFast := flags.String("small-fast-model", "", "Claude Code fast model")
+		jsonOutput := flags.Bool("json", false, "write JSON")
+		home := flags.String("home", "", "override the home directory")
+		if err := flags.Parse(args[2:]); err != nil {
+			return oneerrors.ExitCodes[oneerrors.InvalidRequest]
+		}
+		key := *apiKey
+		if key == "" {
+			key = os.Getenv("ONEAGENT_API_KEY")
+		}
+		core := newCLIUseCases(*home)
+		ctx, stop := flagsContext()
+		defer stop()
+		result, err := core.ActivateAgent(ctx, app.ActivateAgentOptions{
+			AgentID: args[1], Provider: *providerID, APIBaseURL: *baseURL,
+			APIKey: key, Model: *model, ProfileID: *profileID, SmallFastModel: *smallFast,
+		})
+		if err != nil {
+			return writeError(stdout, stderr, err, *jsonOutput, key)
+		}
+		if *jsonOutput {
+			payload := map[string]any{
+				"ok": true, "agent": result.AgentID, "config": result.Config,
+				"provider": result.Provider, "model": result.Model, "binding": result.Binding,
+				"restart": result.Restart, "next": result.Next,
+			}
+			return writeJSON(stdout, payload)
+		}
+		_, _ = fmt.Fprintf(stdout, "[oneagent] %s -> %s / %s\n", result.AgentID, result.Provider, result.Model)
+		_, _ = fmt.Fprintln(stdout, "[oneagent] "+result.Restart)
+		_, _ = fmt.Fprintln(stdout, "[oneagent] next: "+result.Next)
+		return 0
+	default:
+		return writeError(stdout, stderr, oneerrors.New(oneerrors.InvalidRequest, "Unknown agent command"), false, "")
+	}
+}
+
+type installCLIFlags struct {
+	Agent          string
+	Provider       string
+	APIBaseURL     string
+	APIKey         string
+	Model          string
+	SmallFastModel string
+	RegisterURL    string
+	Channel        string
+	InstallAgent   bool
+	CheckOnly      bool
+	SkipTest       bool
+	NoOpen         bool
+	JSON           bool
+	Locked         bool
+	Latest         bool
+	Registry       string
+	Home           string
+	Timeout        int
+}
+
+func runInstall(args []string, stdout, stderr io.Writer) int {
+	flags := flag.NewFlagSet("oneagent", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	options := installCLIFlags{}
+	flags.StringVar(&options.Agent, "agent", "codex", "Agent ID; comma-separated for several")
+	flags.StringVar(&options.Provider, "provider", "ppio", "Provider ID")
+	flags.StringVar(&options.APIBaseURL, "api-base-url", "", "custom Provider base URL")
+	flags.StringVar(&options.APIKey, "api-key", "", "API key")
+	flags.StringVar(&options.Model, "model", "", "model ID")
+	flags.StringVar(&options.SmallFastModel, "small-fast-model", "", "Claude Code fast model")
+	flags.StringVar(&options.RegisterURL, "register-url", "", "registration URL")
+	flags.StringVar(&options.Channel, "channel", "direct", "launch channel")
+	flags.BoolVar(&options.InstallAgent, "install-agent", false, "install missing Agent packages")
+	flags.BoolVar(&options.CheckOnly, "check-agent-only", false, "only inspect Agents")
+	flags.BoolVar(&options.SkipTest, "skip-test", false, "skip Provider probes")
+	flags.BoolVar(&options.NoOpen, "no-open", false, "do not open registration URL")
+	flags.BoolVar(&options.JSON, "json", false, "write JSON")
+	flags.BoolVar(&options.Locked, "locked-version", false, "enforce locked versions")
+	flags.BoolVar(&options.Latest, "latest", false, "install latest version")
+	flags.StringVar(&options.Registry, "registry", "", "package registry mirror or HTTPS URL")
+	flags.StringVar(&options.Home, "home", "", "override the home directory")
+	flags.IntVar(&options.Timeout, "timeout", 180, "operation timeout in seconds")
+	if err := flags.Parse(args); err != nil {
+		return oneerrors.ExitCodes[oneerrors.InvalidRequest]
+	}
+	if options.Locked && options.Latest {
+		return writeError(stdout, stderr, oneerrors.New(oneerrors.InvalidRequest, "--locked-version and --latest cannot be used together"), options.JSON, "")
+	}
+	key, err := resolveCLIKey(options, stderr)
+	if err != nil {
+		return writeError(stdout, stderr, err, options.JSON, key)
+	}
+	agents := splitAgents(options.Agent)
+	if len(agents) == 0 {
+		return writeError(stdout, stderr, oneerrors.New(oneerrors.InvalidRequest, "At least one Agent is required"), options.JSON, key)
+	}
+	if options.Timeout <= 0 {
+		return writeError(stdout, stderr, oneerrors.New(oneerrors.InvalidRequest, "timeout must be greater than zero"), options.JSON, key)
+	}
+	core := newCLIUseCases(options.Home)
+	ctx, stop := flagsContext()
+	defer stop()
+	result, err := core.InstallAgents(ctx, app.InstallAgentsOptions{
+		Agents: agents, Provider: options.Provider, APIBaseURL: options.APIBaseURL,
+		APIKey: key, Model: options.Model, SmallFastModel: options.SmallFastModel,
+		Configure: !options.CheckOnly, InstallAgent: options.InstallAgent,
+		CheckAgentOnly: options.CheckOnly, SkipTest: options.SkipTest,
+		LockedVersion: options.Locked, Latest: options.Latest,
+		Timeout: time.Duration(options.Timeout) * time.Second, Registry: options.Registry,
+	})
+	if err != nil {
+		if code, ok := interruptExitCode(ctx); ok {
+			return code
+		}
+		return writeError(stdout, stderr, err, options.JSON, key)
+	}
+	if options.JSON {
+		return writeJSON(stdout, result)
+	}
+	if result.Log != "" {
+		_, _ = fmt.Fprintln(stdout, result.Log)
+	}
+	for line := range strings.SplitSeq(result.Next, "\n") {
+		if strings.TrimSpace(line) != "" {
+			_, _ = fmt.Fprintln(stdout, "[oneagent] next: "+line)
+		}
+	}
+	if result.OK {
+		return 0
+	}
+	return result.Code
+}
+
+func splitAgents(raw string) []string {
+	parts := strings.Split(raw, ",")
+	result := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if value := strings.TrimSpace(part); value != "" {
+			result = append(result, value)
+		}
+	}
+	return result
+}
+
+func newCLIUseCases(home string) *app.UseCases {
+	info := platform.Current()
+	current := process.Current()
+	return app.NewUseCases(app.StatusOptions{
+		Home: home, Platform: info, Runner: current, Environment: current.Env,
+	})
+}
+
+func resolveCLIKey(options installCLIFlags, stderr io.Writer) (string, error) {
+	if options.CheckOnly {
+		return "", nil
+	}
+	if value := os.Getenv("ONEAGENT_API_KEY"); value != "" {
+		return value, nil
+	}
+	if options.APIKey != "" {
+		return options.APIKey, nil
+	}
+	if !stdinIsTerminal() {
+		return "", oneerrors.New(oneerrors.InvalidRequest, "API key is required; set ONEAGENT_API_KEY or pass --api-key (pasting interactively needs a TTY)")
+	}
+	registration := options.RegisterURL
+	if registration == "" {
+		if home, ok := catalog.ProviderByID(options.Provider); ok {
+			registration = home.Home
+		} else {
+			registration, _ = provider.ProviderHome("ppio")
+		}
+	}
+	if !options.NoOpen {
+		_ = openRegistrationURL(registration)
+	}
+	_, _ = fmt.Fprintln(stderr, "Create or copy an API key from: "+registration)
+	_, _ = fmt.Fprint(stderr, "Paste API key: ")
+	line, err := bufio.NewReader(os.Stdin).ReadString('\n')
+	if err != nil && len(line) == 0 {
+		return "", oneerrors.New(oneerrors.InvalidRequest, "API key is required")
+	}
+	return strings.TrimSpace(line), nil
+}
+
+func stdinIsTerminal() bool {
+	info, err := os.Stdin.Stat()
+	return err == nil && info.Mode()&os.ModeCharDevice != 0
+}
+
+func openRegistrationURL(value string) error {
+	parsed, err := provider.ValidateBaseURL(value)
+	if err != nil {
+		// Provider home URLs end in a path and satisfy the same URL safety rules;
+		// preserve the stable request error if a caller supplied an unsafe value.
+		return err
+	}
+	var command string
+	var args []string
+	switch runtime.GOOS {
+	case "darwin":
+		command, args = "open", []string{parsed}
+	case "windows":
+		command, args = "rundll32", []string{"url.dll,FileProtocolHandler", parsed}
+	default:
+		command, args = "xdg-open", []string{parsed}
+	}
+	return exec.Command(command, args...).Start()
+}
+
+func writeValue(stdout io.Writer, value any, jsonOutput bool) int {
+	if jsonOutput {
+		return writeJSON(stdout, value)
+	}
+	_, _ = fmt.Fprintln(stdout, "OneAgent status is available with --json")
+	return 0
+}
+
+func writeJSON(stdout io.Writer, value any) int {
+	encoder := json.NewEncoder(stdout)
+	encoder.SetEscapeHTML(false)
+	if err := encoder.Encode(value); err != nil {
+		return oneerrors.ExitCodes[oneerrors.InternalError]
+	}
+	return 0
+}
+
+func writeError(stdout, stderr io.Writer, err error, jsonOutput bool, secret string) int {
+	oneErr := oneerrors.As(err)
+	if jsonOutput {
+		if code := writeJSON(stdout, oneErr.APIShape()); code != 0 {
+			return code
+		}
+		return oneErr.ExitCode
+	}
+	message := oneErr.Message
+	if secret != "" {
+		message = strings.ReplaceAll(message, secret, "[redacted]")
+	}
+	_, _ = fmt.Fprintln(stderr, "[oneagent] error: "+message)
+	return oneErr.ExitCode
+}
+
+// helpRequested reports whether the argument list asks for usage rather than an
+// operation. Go's flag package treats -h as a parse error and exits non-zero;
+// the wrapper contract expects help to exit 0, so handle it before any FlagSet
+// sees the arguments.
+func helpRequested(args []string) bool {
+	for _, arg := range args {
+		switch arg {
+		case "-h", "--help", "help":
+			return true
+		case "--":
+			return false
+		}
+	}
+	return false
+}
+
+// printUsage keeps the wrapper's public flag names and double-dash form stable.
+func printUsage(stdout io.Writer) {
+	// One write keeps help safe for callers piping it into
+	// `grep -q`, which closes the pipe on its first match; line-by-line writes
+	// would take a SIGPIPE mid-help and fail the caller's pipeline.
+	lines := []string{
+		"usage: oneagent [--agent AGENT] [--provider PROVIDER]",
+		"                [--api-base-url API_BASE_URL] [--api-key API_KEY]",
+		"                [--model MODEL] [--small-fast-model MODEL]",
+		"                [--register-url URL] [--channel CHANNEL] [--install-agent]",
+		"                [--check-agent-only] [--skip-test] [--no-open] [--json]",
+		"                [--locked-version] [--latest] [--registry REGISTRY]",
+		"                [--timeout SECONDS]",
+		"       oneagent status [--json]",
+		"       oneagent agent list [--json]",
+		"       oneagent agent set AGENT_ID [--provider PROVIDER] [--model MODEL]",
+		"                                   [--api-base-url URL] [--api-key API_KEY]",
+		"                                   [--profile PROFILE] [--json]",
+		"       oneagent --version",
+		"",
+		"Install or configure one Agent with OneAgent",
+		"",
+		"options:",
+		"  -h, --help            show this help message and exit",
+		"  --agent AGENT         Agent ID; comma-separated for several",
+		"  --provider PROVIDER   Provider ID; defaults to ppio",
+		"  --api-base-url API_BASE_URL",
+		"                        Custom Provider base URL",
+		"  --api-key API_KEY     API key; prefer ONEAGENT_API_KEY",
+		"  --model MODEL         Defaults to the provider's probe model",
+		"  --small-fast-model MODEL",
+		"                        Claude Code only: a cheaper fast/background model",
+		"  --register-url URL    Registration URL to open when a key is missing",
+		"  --channel CHANNEL     Launch channel recorded with the install",
+		"  --install-agent       Install missing Agent packages",
+		"  --check-agent-only    Only inspect Agents; writes no configuration",
+		"  --skip-test           Skip Provider probes",
+		"  --no-open             Do not open the registration URL",
+		"  --json                Write a JSON result",
+		"  --locked-version      Enforce the version in agents.lock.json",
+		"  --latest              Install the latest version instead of the locked one",
+		"  --registry REGISTRY   Package registry: a mirror id (official, npmmirror) or",
+		"                        an https:// URL. Defaults to the official registry.",
+		"  --timeout SECONDS     Operation timeout in seconds; defaults to 180",
+	}
+	_, _ = fmt.Fprintln(stdout, strings.Join(lines, "\n"))
+}
+
+// flagsContext cancels the running operation on the first interrupt so provider
+// requests and package-manager subprocesses stop with it. A second interrupt
+// falls through to the runtime's default handler.
+func flagsContext() (context.Context, context.CancelFunc) {
+	return signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+}
+
+// interruptExitCode reports the shell convention for an interrupted command,
+// matching the shell convention for an interrupted command. An interrupt is
+// not an operation failure, so no error payload is written for it.
+func interruptExitCode(ctx context.Context) (int, bool) {
+	if ctx.Err() == nil {
+		return 0, false
+	}
+	return 130, true
+}
+
+func sortedBindingIDs(bindings map[string]profileStore.AgentBinding) []string {
+	ids := make([]string, 0, len(bindings))
+	for id := range bindings {
+		ids = append(ids, id)
+	}
+	sort.Strings(ids)
+	return ids
+}
diff --git a/cmd/oneagent/main_test.go b/cmd/oneagent/main_test.go
new file mode 100644
index 00000000..7016bce7
--- /dev/null
+++ b/cmd/oneagent/main_test.go
@@ -0,0 +1,147 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/app"
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+)
+
+func TestFlatInstallCLIEmitsStructuredGuideResult(t *testing.T) {
+	home := t.TempDir()
+	var stdout, stderr bytes.Buffer
+	code := run([]string{"--agent", "openclaw", "--check-agent-only", "--json", "--home", home}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("exit=%d stderr=%s", code, stderr.String())
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["ok"] != true {
+		t.Fatalf("payload=%v", payload)
+	}
+	results, ok := payload["results"].([]any)
+	if !ok || len(results) != 1 || results[0].(map[string]any)["status"] != "guide-only" {
+		t.Fatalf("results=%v", payload["results"])
+	}
+}
+
+func TestAgentSetAndListCLIUseGoBindingsWithoutLeakingKey(t *testing.T) {
+	home := t.TempDir()
+	var stdout, stderr bytes.Buffer
+	code := run([]string{"agent", "set", "codex", "--provider", "ppio", "--model", "model-a", "--api-key", "cli-secret", "--json", "--home", home}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("set exit=%d stderr=%s", code, stderr.String())
+	}
+	if strings.Contains(stdout.String(), "cli-secret") {
+		t.Fatal("API key appeared in agent set output")
+	}
+	var setPayload map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &setPayload); err != nil || setPayload["provider"] != "ppio" {
+		t.Fatalf("set payload=%s err=%v", stdout.String(), err)
+	}
+	if _, err := os.Stat(filepath.Join(home, ".oneagent", "agents", "codex.json")); err != nil {
+		t.Fatal(err)
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	code = run([]string{"agent", "list", "--json", "--home", home}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("list exit=%d stderr=%s", code, stderr.String())
+	}
+	var listPayload struct {
+		OK     bool                      `json:"ok"`
+		Agents map[string]map[string]any `json:"agents"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &listPayload); err != nil || !listPayload.OK {
+		t.Fatalf("list payload=%s err=%v", stdout.String(), err)
+	}
+	if listPayload.Agents["codex"]["model"] != "model-a" {
+		t.Fatalf("agents=%v", listPayload.Agents)
+	}
+}
+
+// The compatibility wrappers and tests/install_test.sh grep this help text and
+// treat a non-zero exit as a failure, so help keeps the wrapper's contract:
+// exit 0, double-dash flag names, one write.
+func TestHelpMatchesTheCLIContract(t *testing.T) {
+	for _, args := range [][]string{{"--help"}, {"-h"}, {"help"}, {"--agent", "codex", "--help"}} {
+		var stdout, stderr bytes.Buffer
+		if code := run(args, &stdout, &stderr); code != 0 {
+			t.Fatalf("%v exit=%d stderr=%s", args, code, stderr.String())
+		}
+		help := stdout.String()
+		for _, flagName := range []string{
+			"--register-url URL", "--agent AGENT", "--check-agent-only",
+			"--locked-version", "--latest", "--registry REGISTRY", "--skip-test",
+		} {
+			if !strings.Contains(help, flagName) {
+				t.Fatalf("%v help is missing %q", args, flagName)
+			}
+		}
+		if stderr.Len() != 0 {
+			t.Fatalf("%v wrote help diagnostics to stderr: %s", args, stderr.String())
+		}
+	}
+}
+
+// An interrupt is not an operation failure: it exits with the shell convention
+// and writes no error payload, matching the CLI interrupt path.
+func TestInterruptExitCodeUsesShellConventionWithoutErrorPayload(t *testing.T) {
+	if code, interrupted := interruptExitCode(context.Background()); interrupted || code != 0 {
+		t.Fatalf("uncancelled context reported code=%d interrupted=%v", code, interrupted)
+	}
+	cancelled, cancel := context.WithCancel(context.Background())
+	cancel()
+	code, interrupted := interruptExitCode(cancelled)
+	if !interrupted || code != 130 {
+		t.Fatalf("cancelled context reported code=%d interrupted=%v", code, interrupted)
+	}
+}
+
+// The install path must observe cancellation rather than run to completion, so
+// a signal stops provider requests and package-manager subprocesses with it.
+func TestInstallHonoursACancelledContext(t *testing.T) {
+	home := t.TempDir()
+	core := app.NewUseCases(app.StatusOptions{Home: home, Platform: platform.Current()})
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err := core.InstallAgents(ctx, app.InstallAgentsOptions{
+		Agents: []string{"codex"}, Provider: "ppio", APIKey: "cancel-secret",
+		Model: "model-a", Configure: true, SkipTest: true, Timeout: 30 * time.Second,
+	})
+	if err == nil {
+		t.Fatal("a cancelled install returned no error")
+	}
+	if strings.Contains(err.Error(), "cancel-secret") {
+		t.Fatalf("cancellation error leaked the API key: %v", err)
+	}
+	if _, statErr := os.Stat(filepath.Join(home, ".codex", "config.toml")); statErr == nil {
+		t.Fatal("a cancelled install still wrote Agent configuration")
+	}
+}
+
+func TestFlatCLIRejectsEmptyAgentListAndConflictingVersionModes(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	if code := run([]string{"--agent", ",", "--check-agent-only"}, &stdout, &stderr); code != 2 || !strings.Contains(stderr.String(), "At least one Agent") {
+		t.Fatalf("empty agents exit=%d stderr=%q", code, stderr.String())
+	}
+	stdout.Reset()
+	stderr.Reset()
+	if code := run([]string{"--check-agent-only", "--latest", "--locked-version", "--json"}, &stdout, &stderr); code != 2 {
+		t.Fatalf("conflicting modes exit=%d output=%q", code, stdout.String())
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil || payload["error_code"] != "INVALID_REQUEST" {
+		t.Fatalf("error payload=%q err=%v", stdout.String(), err)
+	}
+}
diff --git a/distribution/channels.json b/distribution/channels.json
deleted file mode 100644
index b52aae7b..00000000
--- a/distribution/channels.json
+++ /dev/null
@@ -1,119 +0,0 @@
-{
-  "schema_version": 1,
-  "product": {
-    "name": "OneAgent",
-    "tagline": "用一个可信的本地流程，激活你自己的 Agent、账号和 Provider。",
-    "release_policy": "security/",
-    "privacy_policy": "security/#privacy"
-  },
-  "channels": {
-    "technical-preview-unsigned": {
-      "label": "未签名技术预览版",
-      "published_at": "2026-07-28T00:00:00Z",
-      "targets": [
-        {
-          "platform": "macos",
-          "arch": "arm64",
-          "status": "available",
-          "verification": {
-            "native_build": true,
-            "cleanroom": "verified",
-            "evidence": "security/#release-evidence"
-          },
-          "mirrors": [
-            {
-              "id": "website",
-              "label": "官网下载",
-              "kind": "official",
-              "url": "downloads/{file}",
-              "primary": true
-            }
-          ]
-        },
-        {
-          "platform": "macos",
-          "arch": "x64",
-          "status": "verification-pending",
-          "verification": {
-            "native_build": false,
-            "cleanroom": "not-recorded",
-            "evidence": null
-          },
-          "mirrors": []
-        },
-        {
-          "platform": "windows",
-          "arch": "x64",
-          "status": "verification-pending",
-          "verification": {
-            "native_build": false,
-            "cleanroom": "not-recorded",
-            "evidence": null
-          },
-          "mirrors": []
-        },
-        {
-          "platform": "linux",
-          "arch": "x64",
-          "status": "verification-pending",
-          "verification": {
-            "native_build": false,
-            "cleanroom": "not-recorded",
-            "evidence": null
-          },
-          "mirrors": []
-        }
-      ]
-    },
-    "stable": {
-      "label": "Stable",
-      "published_at": null,
-      "targets": [
-        {
-          "platform": "macos",
-          "arch": "arm64",
-          "status": "planned",
-          "verification": {
-            "native_build": false,
-            "cleanroom": "not-recorded",
-            "evidence": null
-          },
-          "mirrors": []
-        },
-        {
-          "platform": "macos",
-          "arch": "x64",
-          "status": "planned",
-          "verification": {
-            "native_build": false,
-            "cleanroom": "not-recorded",
-            "evidence": null
-          },
-          "mirrors": []
-        },
-        {
-          "platform": "windows",
-          "arch": "x64",
-          "status": "planned",
-          "verification": {
-            "native_build": false,
-            "cleanroom": "not-recorded",
-            "evidence": null
-          },
-          "mirrors": []
-        },
-        {
-          "platform": "linux",
-          "arch": "x64",
-          "status": "planned",
-          "verification": {
-            "native_build": false,
-            "cleanroom": "not-recorded",
-            "evidence": null
-          },
-          "mirrors": []
-        }
-      ]
-    }
-  }
-}
diff --git a/docs/ai-agent-kit/00-start-here.md b/docs/ai-agent-kit/00-start-here.md
index fd1dd1f1..c2cbd7c2 100644
--- a/docs/ai-agent-kit/00-start-here.md
+++ b/docs/ai-agent-kit/00-start-here.md
@@ -8,7 +8,7 @@
 
 ## 开始前准备
 
-- 一台可以运行 Python 3 的设备。
+- 一台支持的 macOS、Windows 或 Linux 设备；普通 OneAgent 流程不需要 Python。
 - 一个可用的模型 Provider 账号，或准备注册一个。
 - 你准备使用的 Agent，例如 Codex、Claude Code、OpenCode 或 Aider。
 
@@ -27,13 +27,15 @@
 
 如果你已经熟悉多 Provider 切换，可以在配置方式页面选择 **CC Switch**，然后阅读 [配置工具选择](./03-config-tools.md) 和 [CC Switch 指引](./tools/cc-switch.md)。
 
-## 启动本地 GUI
+## 启动桌面应用
 
 ```bash
-python3 scripts/gui.py
+cd frontend && npm ci && npm run build
+cd ..
+go run -tags wails ./cmd/oneagent-desktop
 ```
 
-GUI 只监听本机 `127.0.0.1`，不会主动暴露到局域网。
+也可以下载对应平台的 `technical-preview-unsigned` 包后直接启动 Wails 应用。
 
 ## 三条安全规则
 
@@ -58,4 +60,3 @@ OneAgent 不提供 VPN、代理、节点订阅或绕过网络限制的配置。
 - 配置工具问题：查看 [配置工具选择](./03-config-tools.md)。
 - Agent 问题：查看 [Agent 分类和安装指引](./04-agent-guides.md)。
 - 请求问题：查看 [第一次请求验证](./05-first-request.md)。
-
diff --git a/docs/ai-agent-kit/04-agent-guides.md b/docs/ai-agent-kit/04-agent-guides.md
index a6ab48a6..1ebc8476 100644
--- a/docs/ai-agent-kit/04-agent-guides.md
+++ b/docs/ai-agent-kit/04-agent-guides.md
@@ -24,8 +24,8 @@
 
 ### Aider
 
-- 自动安装使用 `uv tool` 和本机已有的 Python 3.12，不使用系统级 pip。
-- 缺少 `uv` 或 Python 3.12 时先完成官方前置条件安装；OneAgent 不自动下载 Python。
+- 只有选择 Aider 安装时才使用 `uv tool` 和本机已有的 Python 3.12；其他 Agent 和 OneAgent 自身不需要 Python。
+- 缺少 `uv` 或 Python 3.12 时先完成 Aider 官方前置条件安装；OneAgent 不自动下载运行时。
 - 使用独立环境文件保存 PPIO 配置。
 - 启动前加载环境文件。
 - 使用 `openai/<model>` 形式时，以 Aider 当前版本说明为准。
diff --git a/docs/ai-agent-kit/manifest.md b/docs/ai-agent-kit/manifest.md
index 8b2e7896..60146711 100644
--- a/docs/ai-agent-kit/manifest.md
+++ b/docs/ai-agent-kit/manifest.md
@@ -7,8 +7,6 @@
 | `launcher` | 启动本地 GUI | 否 |
 | `start.sh` | macOS / Linux 启动入口 | 否 |
 | `start.command` | macOS 双击入口 | 否 |
-| `scripts/install.sh` | 检测、安装和写配置 | 运行时输入 |
-| `scripts/verify.sh` | 连通性和模型验证 | 运行时输入 |
 
 ## 文档文件
 
diff --git a/docs/blank-machine-verification-plan.md b/docs/blank-machine-verification-plan.md
index 21b01a04..bf88f467 100644
--- a/docs/blank-machine-verification-plan.md
+++ b/docs/blank-machine-verification-plan.md
@@ -1,189 +1,33 @@
-# 空白机器可用性验证计划（Codex 与 Claude Code）
+# 空白机器可用性验证计划
 
-目标：证明一台没装过任何 Agent 的机器，能用 OneAgent 把 Codex 和 Claude Code 装好并真正跑起来。范围限定这两个自动配置 Agent。
+> 状态：已实施（2026-07-31）。实现入口已从历史脚本切换为 Go CLI、Go RC 命令和 shell cleanroom。
 
-> **实施状态（2026-07-29）**：四层全部落地。`tests/test_install_contract.py`（29 用例，离线）进常规 CI；`tests/real_install_test.sh` 真实安装两个 Agent，官方源与 npmmirror 双路径实测通过，进 RC workflow；`scripts/agent_e2e_smoke.py` 需真实 Key，手动运行；integrity 校验已在 `install_locked_agent()` 生效。`installer.py` 保持 274/274 分支、零 partial。
+## 验证层级
 
-两个结论：
+| 层级 | 入口 | 证明内容 |
+| --- | --- | --- |
+| RC 安装 | `go run ./cmd/oneagent-rc verify-agents` | 多 Agent 隔离安装、版本和可执行文件 |
+| 配置采用 | `go run ./cmd/oneagent-rc adopted` | Codex/Claude Code 是否真正读取丢弃端点配置 |
+| Provider | `go run ./cmd/oneagent-provider-smoke` | models、Chat、Responses、Anthropic Messages |
 
-**现有验证设施覆盖不到这条链路。** 不是测试写得不够多，而是所有既有测试都绕开了「真的装包」和「真的连服务商」这两步。已手动补跑（第 4 节），装得上，但结论未固化成可重复的脚本。
+普通 CI 不访问 registry 或真实 Provider；Release Candidate workflow 在受保护环境中执行真实网络检查。Aider 需要其上游声明的 Python 3.12，但不纳入普通 Go/Wails cleanroom。
 
-**国内网络下需要授权镜像，这已落在产品边界内。** 镜像与官方源的 integrity 逐字节相同，属「同包不同渠道」而非绕过网络限制，详见 3.5 节。
+## 关键断言
 
-## 1. 现有设施实际验了什么
+- npm prefix 必须排在 PATH 首位，不能由开发机全局 Agent 假通过。
+- 安装后每个 Agent 的版本必须等于 `agents.lock.json`。
+- 配置文件和 secret 文件使用预期的 `0700/0600` 权限。
+- 真实用户 HOME 在测试前后快照必须完全一致。
+- API Key 不出现在 profile、CLI JSON、日志或测试附件。
+- 配置指向 `127.0.0.1:9` 时，采用配置的 Agent 应报连接失败而不是登录/认证错误。
+- release check 必须拒绝 source map、远程资源、secret、Agent 二进制和旧 runtime。
 
-| 设施 | 真装包 | 真连 Provider | 实际覆盖 |
-| --- | --- | --- | --- |
-| `tests/test_core.py` 等 162 个 Python 用例 | 否，`Runtime.runner` 被替换 | 否 | 配置文件内容、错误码、权限 |
-| `tests/install_test.sh` (263 行) | 否，全程 `--skip-test` | 否 | CLI 参数契约、退出码 |
-| `tests/macos_cleanroom_test.sh` (301 行) | **否** | 否，指向 `127.0.0.1:9` | 干净 HOME 下写配置、文件权限 0600/0700、密钥不落盘 |
-| `scripts/run_container_cleanroom.sh` | 否 | 否 | Linux 断网环境下的策略扫描 |
-| `scripts/verify_locked_agents.py`（RC workflow 调用） | **是** | 否 | 五个 Agent 全部真实安装、隔离前缀、版本断言 |
-| `scripts/provider_rc_smoke.py` | 不适用 | **是** | Provider 端点可达性 |
-
-**更正**：先前记录的「没有任何一层真的装包」不成立。`scripts/verify_locked_agents.py` 一直在真实安装：`install_agent=True`、`locked_version=True`、隔离的 npm 前缀与 uv 目录、剔除带 `KEY`/`TOKEN`/`SECRET` 的环境变量，装完还用 `installed_version()` 断言版本相符（`:113`），且覆盖全部五个自动配置 Agent。它由 RC workflow 的 `Install and verify all locked Agents` 步骤调用。**真实安装本来就有覆盖，缺的是它之后的两步。**
-
-实际的三个缺口：
-
-**macOS cleanroom 链接了真实 npm 却从不用它。** `tests/macos_cleanroom_test.sh:40` 把真实 `npm` 链进干净 PATH，看起来具备安装能力，但 `:235-244` 的循环只传 `--provider/--model/--skip-test`，走纯配置路径。它验证「配置写得对」，不验证「Agent 装得上」——后者由 `verify_locked_agents.py` 在另一处覆盖。
-
-**可执行文件是否落到 PATH 无人断言。** `verify_locked_agents.py` 用注入的 `isolated_which` 在自己构造的 PATH 里查找，验证的是「OneAgent 认为它装好了」。真实机器上 npm 全局前缀的差异是最常见的故障点，而这一步没有独立验证。
-
-**`integrity` 记录了但从不校验。** `agents.lock.json` 为两个 Agent 都记了 `sha512-`，`tests/test_release_policy.py:36` 也断言它存在，但 `install_locked_agent()` 全函数不出现 `integrity`，只执行 `npm install -g <name>@<version>`。**版本锁住了，字节没有。**
-
-## 2. 待验证的链路
-
-空白机器到「Agent 能回答一个请求」，中间有六个环节，每一个都可能独立失败：
-
-1. **前置条件** —— Node.js 是否存在、版本是否够；Windows 上 Claude Code 还要求 `git`（lock 里的 `windows_prerequisites`）。
-2. **装包** —— `npm install -g @openai/codex@0.145.0` 与 `@anthropic-ai/claude-code@2.1.217` 在真实 registry 上是否可解析、可安装。
-3. **可执行文件落到 PATH** —— 装完之后 `runtime.which("codex")` / `which("claude")` 是否真的找得到。npm 全局前缀在不同机器上差异很大，这一步是最常见的实际故障点。
-4. **版本一致** —— `codex --version` 报出的是否就是锁定的版本。
-5. **写配置** —— 这一环现有 cleanroom 已覆盖，且是唯一被覆盖的。
-6. **Agent 真的能用** —— 带着写好的配置和真实 Key，Codex 和 Claude Code 能否各自完成一次请求。这是「可用」的唯一判据，也是目前完全空白的一环。
-
-环节 3 与 6 是这次要补的重点：前者决定装完能不能被调用，后者决定配置写对了是否等于能用。
-
-## 3. 检查计划
-
-分三层，按成本和可重复性从低到高。第一层进常规 CI，第二三层手动或按发行触发——**真实装包与真实 Key 不能进常规 CI**，那会让每次提交都打 registry 和 Provider。
-
-### 第一层：装包契约（进常规 CI，无网络）
-
-补 `tests/test_install_contract.py`，用替换过的 `Runtime.runner` 断言即将执行的命令，不真的执行：
-
-- Codex 与 Claude Code 的安装命令恰好是 `npm install -g <name>@<locked>`，版本取自 lock 而非硬编码。
-- `--latest` 未指定时命令里必须带 `@<version>`；这是版本锁定的直接体现。
-- 已装且版本相符时不重复安装（`install_locked_agent` 的短路分支）。
-- 已装但版本落后时会重装。
-- Node.js 缺失时报 `PREREQUISITE_MISSING` 而不是让 npm 自己失败。
-- Windows 平台缺 `git` 时 Claude Code 报 `PREREQUISITE_MISSING`（用 `Runtime(os_id="windows")` 模拟）。
-
-这一层保证命令构造正确，能在几毫秒内跑完，且不依赖外网。
-
-### 第二层：真实安装 cleanroom（手动 / 发行前）
-
-新增 `tests/real_install_test.sh`，与 macOS cleanroom 同样的隔离方式（干净 `HOME`、`env -i`、前后快照真实 HOME 确认零污染），但**真的装包**：
-
-1. 断言起点为空：`codex` 与 `claude` 都不在 PATH 上，干净 HOME 下无 `.codex` / `.claude`。
-2. 用真实 npm 安装两个 Agent 的锁定版本，npm 全局前缀指向干净 HOME 内的临时目录（避免污染真实机器）。
-3. **断言可执行文件确实出现在 PATH 上**——环节 3，现有测试完全没有覆盖。
-4. 断言 `codex --version` 与 `claude --version` 报出锁定版本，不是别的版本。
-5. 断言 `/api/status` 把两者报成 `installed: true` 且版本相符（走真实 HTTP，与 `gui_smoke_test.py` 同样方式）。
-6. 断言真实 HOME 前后快照一致——这是 macOS cleanroom 已有的做法，直接沿用。
-
-只装这两个 Agent，不碰另外三个。默认不在 CI 跑；给 `release-candidate.yml` 加一个显式 job，并把那个名不副实的 `native-build-and-agent-install` 改成实际执行安装，或改名为它真正做的事。
-
-### 第三层：端到端可用性（手动，需真实 Key）
-
-新增 `scripts/agent_e2e_smoke.py`，在第二层基础上加真实 Provider：
-
-1. 用真实 Key 走完整 `install_many`（不带 `--skip-test`），让协议探测真实执行——Codex 走 Responses，Claude Code 走 Anthropic Messages，两者协议不同，这正是需要分别验证的原因。
-2. 读回写好的配置，确认 Codex 的 `config.toml` 里 `env_key` 指向的环境变量文件存在且含 Key，Claude Code 的 `settings.json` 里四个 `ANTHROPIC_*` 变量齐全。
-3. **实际调用两个 Agent 各完成一次最小请求**，断言退出码为 0 且有输出。这是唯一能证明「可用」的一步。
-4. 断言全过程的日志里不出现 Key 明文（`redact` 生效），沿用 macOS cleanroom 的 `grep -R -Fq` 手法。
-
-只手动运行，需要 `ONEAGENT_API_KEY` 与一个可用 Provider。产出写进 `docs/release-evidence/`，与现有 cleanroom 证据同格式。
-
-## 3.5 安装源可达性：授权镜像（已核实可行）
-
-上面第 2 节的环节 2 假设 `registry.npmjs.org` 可达。在国内网络下这个假设经常不成立，而这恰好是 [产品边界基线](product-boundary-baseline.md) 已经预留了答案的场景。
-
-### 为什么这不是「绕过网络限制」
-
-基线第 5 节的软件获取策略把「授权镜像」列为优先级 2，条件是**有许可证、版本锁定、校验值和上游地址**；第 3.2 节允许「许可证允许的开源软件镜像」与「同包镜像」，同时第 4 节禁止「翻墙下载」「免代理访问受限网站」和「把 OneAgent 的服务器作为中转代理」。
-
-分界线在于：**换 registry 是换取包的渠道，不是代理用户的网络。** OneAgent 不建隧道、不转发流量、不接触用户与镜像之间的连接，只是把 npm 的下载地址指向另一个同样公开可达的地址。这与基线允许「网盘和企业云盘上的同包镜像」是同一性质。
-
-已核实的关键事实（2026-07-29）：
+## 运行
 
+```bash
+go build -o bin/oneagent ./cmd/oneagent
+go run ./cmd/oneagent-rc verify-agents
+go run ./cmd/oneagent-rc adopted
 ```
-@openai/codex@0.145.0
-  官方 dist.integrity  sha512-/PSPSFujjjmiyVFvG2yu/grOFhsWdokTH8t2KGWhXSo/M5n/dIDsnbsnO82/7bLtIoDuzQf7ATBUMWqPWQINlQ==
-  镜像 dist.integrity  sha512-/PSPSFujjjmiyVFvG2yu/grOFhsWdokTH8t2KGWhXSo/M5n/dIDsnbsnO82/7bLtIoDuzQf7ATBUMWqPWQINlQ==
-
-@anthropic-ai/claude-code@2.1.217
-  官方 dist.integrity  sha512-EIcc3GmI7x+qPlKCjpcLIjCh7YOaCFbOqKfL4BmwZS6QmtduVNT5E98oyr8n2cxsgeWVbnQ0mSVljTw5C/kFtA==
-  镜像 dist.integrity  sha512-EIcc3GmI7x+qPlKCjpcLIjCh7YOaCFbOqKfL4BmwZS6QmtduVNT5E98oyr8n2cxsgeWVbnQ0mSVljTw5C/kFtA==
-```
-
-两者**逐字节相同，且正好等于 `agents.lock.json` 里已记录的 `integrity`**。所以这不是「换了个源装到不同的东西」，而是同一份包的另一个渠道——基线第 3.2 节要求的「同一版本的所有渠道必须使用相同产物和相同 SHA-256」天然满足。
-
-实测从镜像安装两个 Agent 共 4 秒完成，版本报告 `codex-cli 0.145.0` 与 `2.1.217 (Claude Code)`，与锁定一致。
-
-### Claude Code 的许可证需要单独说明
-
-`agents.lock.json` 记录 Claude Code 的 license 是 **Proprietary**，而基线第 4 节禁止「未经许可重新分发商业 Agent 包体」。这一条**不构成障碍，但理由必须写准**：
-
-我们不重新分发任何包体。npmmirror 是上游 registry 的公开只读镜像，包由版权方自己发布到 npm；OneAgent 只是让用户的 npm 从哪个地址取包。禁止的是我们自己托管、重打包或再分发——那需要授权，而指向一个公开镜像不需要。
-
-**因此实现上有一条硬性约束：绝不把 Agent 包体放进 OneAgent 自己的任何渠道**（发行包、对象存储、网盘）。镜像只能是第三方公开 registry，不能是我们运营的存储。
-
-### 实现方式
-
-落点很干净，因为 `Runtime.env` 已经是可注入字段，且 `install_locked_agent()` 已经把 `env=runtime.env` 传给 runner。所以不需要改命令构造，只需要在 env 里设 `npm_config_registry`：
-
-- `catalog.py` 增一个 `PACKAGE_MIRRORS` 常量，声明可选镜像及其上游地址与用途说明。每个条目必须带上游 registry 地址，满足基线「有上游地址」的要求。
-- 新增 `--registry <url>` CLI 参数与对应的请求字段；**默认保持官方源**，镜像永远是用户显式选择的结果，不做自动探测切换。这一点重要：自动切换会让用户不知道包从哪来。
-- 只接受 HTTPS，且校验 URL 形态（复用 `providers.py` 里 base URL 校验的同类做法），拒绝 `http://` 和畸形值。
-- 安装日志里记录实际使用的 registry。用户必须能事后知道包是从哪个地址来的。
-- 前端在高级项里提供镜像选择，收起时说明「默认使用官方源，网络不可达时可选国内镜像」。
-
-### 与 integrity 校验的关系
-
-**镜像使这一层从可选变成必要。** 官方源下 integrity 只是「记而不验」的落差；一旦允许第三方镜像，「同包」就从 npm 的信任模型变成了我们自己的声明。`npm install` 会用 registry 自己返回的 integrity 校验下载，但那是镜像说什么就信什么。
-
-所以引入镜像的同时，`install_locked_agent()` 应当把 `agents.lock.json` 里记录的 integrity 与实际安装的包核对——这是把「授权镜像」从口头承诺变成可执行检查的唯一方式，也正是基线第 5 节要求镜像必须有「校验值」的本意。
-
-### 测试
-
-- `PACKAGE_MIRRORS` 每个条目都有 HTTPS 地址、上游地址和说明（同 `test_release_policy.py` 对 lock 的断言风格）。
-- `--registry` 未指定时，env 里不出现 `npm_config_registry`——默认行为不变。
-- 指定时 env 正确携带，且命令构造不因此改变（版本锁定不受影响）。
-- `http://` 与畸形 URL 被拒。
-- 安装日志包含实际 registry，且不含任何密钥。
-- 第二层的真实安装脚本增加一轮镜像安装，断言装出的版本与官方源一致。
-
-### 不做
-
-- **不自动探测网络并切换源。** 用户显式选择，否则包的来源变成隐式行为。
-- **不自建镜像，不把 Agent 包体放进 OneAgent 的任何渠道。** 见上面的许可证说明。
-- **不为 registry 做代理、隧道或任何形式的流量转发。** 基线第 4 节明确禁止，且这与换 registry 是完全不同的两件事。
-- **不因为镜像可用就放宽版本锁定。** 镜像上取不到锁定版本时应当报「安装源不可达」，而不是退到别的版本——基线第 5 节最后一段已经规定了这个行为。
-
-### 第四层：integrity 校验
-
-`integrity` 目前记而不验：`agents.lock.json` 为两个 Agent 都记了 `sha512-`，`tests/test_release_policy.py:36` 断言它存在，但 `install_locked_agent()` 全函数不出现 `integrity`。**版本锁住了，字节没锁。**
-
-只用官方源时这是一个可以接受的落差——npm 自己会用 registry 返回的 integrity 校验下载，信任链落在 npm 身上。**但一旦引入第三方镜像（3.5 节），这一层就从可选变成必要**：镜像返回的 integrity 是镜像自己说的，我们凭什么相信它与官方一致？答案只能是拿 lock 里记录的值去核对。
-
-所以优先级取决于是否实施 3.5：
-- 只做前三层、不引入镜像 —— 第四层可以留作已知落差，记录在案即可。
-- 实施镜像 —— 第四层必须同时落地，否则「授权镜像」缺了基线第 5 节要求的「校验值」这一条件。
-
-## 4. 现状确认（已执行，2026-07-29）
-
-在写任何新测试之前先手动跑了一遍，用隔离的 `npm_config_prefix` 与干净 `HOME`，不污染本机。环节 1–5 全部通过：
-
-| 环节 | 结果 |
-| --- | --- |
-| 1 前置条件 | Node v22.23.1 / npm 10.9.8 |
-| 2 装包 | 两个锁定版本在 registry 上均存在，`npm install -g` 各 2–3 秒完成 |
-| 3 落到 PATH | `codex` 与 `claude` 都出现在前缀的 `bin/` 下，可调用 |
-| 4 版本一致 | `codex-cli 0.145.0`、`2.1.217 (Claude Code)`，与锁定完全相符 |
-| 5 写配置 | 两个 Agent 的配置均落地，权限 0600；`config.toml` 的 `env_key` 正确指向 `ONEAGENT_API_KEY_CODEX`；`profile.json` 无明文密钥 |
-
-同时确认 `status_payload()` 在隔离环境中把两者都报成 `installed: true` 且版本匹配——**OneAgent 对真实安装的检测是准的**，此前只有替换过 `runner` 的单元测试覆盖这一点。
-
-**所以「装得上」不再是假设，锁定版本无需调整。** 剩下唯一未验证的是环节 6（带真实 Key 让两个 Agent 各完成一次请求），需要可用的 Provider 凭据，属第三层。
-
-这次是手动执行、结论未固化。第二层的价值就是把上面这张表变成可重复运行的脚本，避免下次锁定版本变更后又要靠手工确认。
-
-## 5. 明确不做
-
-- **不在常规 CI 里真实装包或连 Provider。** 每次提交打 registry 与服务商既慢又会触发限流，也让 CI 结果依赖外部可用性。这也是现有 CI 用假 npm 的正当理由——问题不在于它用了假 npm，而在于**没有任何一层用真的**。
-- **不验证另外三个 Agent。** 本轮范围就是 Codex 与 Claude Code。
-- **不为 guide-only Agent 做安装验证。** 它们按设计不由 OneAgent 安装。
-- **不改 `agents.lock.json` 的锁定版本**，除非第 4 节的现状确认表明当前版本已装不上。
 
-相关文档：[产品边界基线](product-boundary-baseline.md)、[三平台 Python 内核与版本锁定 ADR](decisions/ADR-003-three-platform-python-core-and-release-policy.md)。
+真实安装会访问 npm registry，应在隔离网络和可审计的 runner 中运行。
diff --git a/docs/cc-switch-reference-notes.md b/docs/cc-switch-reference-notes.md
index 03fc544d..a5c797cf 100644
--- a/docs/cc-switch-reference-notes.md
+++ b/docs/cc-switch-reference-notes.md
@@ -8,7 +8,7 @@
 
 | | CC Switch | OneAgent |
 | --- | --- | --- |
-| 形态 | Tauri 桌面应用（Rust + React） | 本地 HTTP + React，Python 标准库内核 |
+| 形态 | Tauri 桌面应用（Rust + React） | Wails 桌面应用（Go + React） |
 | 职责 | Provider 配置的**存取与切换** | Agent 的**检测、安装、配置** |
 | 配置模型 | 整块存原始配置对象 | 结构化字段，由适配器翻译 |
 | 外围能力 | 本地代理、熔断器、故障转移、用量统计、MCP、skills、prompts、sessions | 无 |
diff --git a/docs/config-chain-audit.md b/docs/config-chain-audit.md
index bcdc7f97..9f388df0 100644
--- a/docs/config-chain-audit.md
+++ b/docs/config-chain-audit.md
@@ -1,133 +1,41 @@
-# 配置链路实测与硬编码审查
+# 配置链审计（已实施）
 
-只验证 Codex 与 Claude Code。问的是两件事：配置写完之后 Agent 是否真的采用；以及支撑这条链路的代码是否可扩展。
+> 更新：2026-07-31。历史审计发现已落实到 Go 核心；本文不再引用已删除的旧实现路径。
 
-两条结论：
+## 当前链路
 
-- **Codex 通，Claude Code 不通。** 我们对 Claude Code 只写 `settings.json`，而它不从那里取认证，实机启动得到 `Not logged in`——但 OneAgent 报的是 `status: configured`。
-- **硬编码规模足以阻碍扩展。** `agents.lock.json` 号称唯一真源，但命令名与配置路径在 Python 里被重复写了一遍，新增一个 Agent 要改 6 处分散代码。
-
-## 1. 实测：配置写完之后 Agent 认不认
-
-方法是把配置指向 `127.0.0.1:9`（丢弃端口）。若 Agent 报连接失败，说明它读到并采用了我们的配置；若报别的，说明配置没生效。
-
-### Codex：通
-
-```
-$ codex exec --skip-git-repo-check "say ok"
-provider: oneagent
-ERROR: Reconnecting... 1/5
-```
-
-`provider: oneagent` 是决定性的——Codex 读了我们写入 `~/.codex/config.toml` 的 `[model_providers.oneagent]`，并按 `base_url` 去连。`env_key = "ONEAGENT_API_KEY_CODEX"` 也生效，密钥经环境变量间接传入。**这条链路完整。**
-
-### Claude Code：不通
-
-```
-$ claude -p "say ok"          # HOME 指向写好 settings.json 的干净目录
-Not logged in · Please run /login
-```
-
-同一份配置改用环境变量直接给，则不再报错（进入连接尝试）：
-
-```
-$ ANTHROPIC_BASE_URL=... ANTHROPIC_AUTH_TOKEN=... claude -p "say ok"
-（无报错输出）
-```
-
-**所以 `settings.json` 的 `env` 块不足以让 Claude Code 认证。** 我们写进去的四个变量：
-
-```json
-{"env": {"ANTHROPIC_BASE_URL": "...", "ANTHROPIC_AUTH_TOKEN": "...",
-         "ANTHROPIC_MODEL": "...", "ANTHROPIC_SMALL_FAST_MODEL": "..."}}
-```
-
-而 OneAgent 对此报告：
-
-```
-status: configured
-next:   claude
-```
-
-**这是本轮最严重的问题**：产品声称配置完成并给出启动命令，用户照做会撞上 `Not logged in`，且没有任何线索指向 OneAgent。相比之下 Codex 之所以能用，正是因为它额外有 `~/.oneagent/agents/codex.env`。
-
-根因在 `install_many`（`installer.py:1137`）与 `activate_agent`（`:1375`）都写着：
-
-```python
-if agent_id in {"codex", "opencode", "kilo-cli"}:
-    write_agent_env(...)
+```text
+agents.lock.json
+      |
+internal/catalog
+      |
+internal/app validation
+      |
+internal/provider protocol/base resolution
+      |
+internal/config adapter + securefs atomic write
+      |
+internal/profile binding/secret store
+      |
+Wails service or cmd/oneagent
 ```
 
-**Claude Code 是唯一被排除在 env 文件之外、却又依赖环境变量的自动配置 Agent。** Aider 有自己的 `aider.env`，另外三个有 `agents/<id>.env`，只有它两头都没有。
+## 已修复的风险
 
-## 2. 硬编码审查
+- Agent 命令、配置路径、版本、平台和 package manager 从 lock manifest 读取。
+- 配置适配器只在 Go 中按 adapter 分派，格式差异不伪装成数据配置。
+- 每个 Agent 的凭据交付方式由 `credential_delivery` 和 `env_vars` 声明。
+- Claude Code 的 native env 与配置文件同步写入，避免出现配置显示完成但运行时未登录。
+- Codex、Claude Code、OpenCode、Kilo CLI、Aider 按各自协议探测。
+- 备份、临时文件、权限和原子替换由 `securefs` 统一处理。
+- RC 的 `adopted` 检查将配置指向丢弃端口，区分网络失败和认证失败。
 
-`agents.lock.json` 每个 auto Agent 已有 `command`、`config_path`、`config_adapter`、`version_args` 等字段。问题是 Python 里又写了一遍，两处会不一致。
-
-| 位置 | 硬编码内容 | 性质 |
-| --- | --- | --- |
-| `installer.py:694-698` | `_next_step` 的五个 Agent 启动命令 | **重复了 lock 的 `command`** |
-| `installer.py:1335` | `_restart_hint` 的四个命令名映射 | **重复了 lock 的 `command`** |
-| `installer.py:1454-1455` | `backups` 手写 `.codex/config.toml` 与 `.claude/settings.json` | **重复了 lock 的 `config_path`** |
-| `installer.py:1137`、`:1375` | 需要 env 文件的 Agent 集合 | 行为未在 lock 声明（第 1 节的缺陷根因） |
-| `installer.py:530`、`:1421` | Windows 上 Claude Code 需要 git | lock 有 `windows_prerequisites`，此处未读它 |
-| `installer.py:712-724` | `_write_agent_config` 按 adapter 分派 | **合理**：适配器是代码，不是数据 |
-| `installer.py:293` | `write_codex_config` 里的 `agent_env_var("codex")` | **合理**：该函数专属 Codex |
-| `providers.py:66`、`:178` | `"claude-code"` 判断 Anthropic 协议 | 已有 `ADAPTER_PROTOCOLS`，此处绕过了它 |
-
-前三项是真正的可维护性问题：同一事实存在两份，改 lock 不会改行为。`:1137` 那项更进一步——它是一个**未被声明的行为**，也正是 Claude Code 失效的原因。
-
-新增一个自动配置 Agent 现在要动：lock 一处 + `_write_agent_config` 分派 + `_next_step` + `_restart_hint` + env 文件名单 + `backups`，共 6 处，其中 4 处纯属重复。
-
-## 3. 要完成的任务
-
-### 任务 1：修 Claude Code 的认证链路（阻塞级）— 已完成
-
-lock 里为每个 auto Agent 增 `credential_delivery`（`oneagent_env` / `native_env` / `config_file`），Claude Code 另有 `env_vars` 声明它自己读的四个变量名。`install_many` 与 `activate_agent` 改读 `needs_env_file(meta)`，不再判断 id 集合；`_next_step` 与 `_restart_hint` 也由 lock 推导。
-
-实测确认（配置指向 `127.0.0.1:9`，按 `next` 指引启动）：
+## 审计门禁
 
+```bash
+go test ./internal/config ./internal/install ./internal/app
+go run ./cmd/oneagent-rc adopted
+go run ./cmd/oneagent-release check release
 ```
-next: source ~/.oneagent/agents/codex.env && codex
-      source ~/.oneagent/agents/claude-code.env && claude
-
-Codex        采用了我们写的 provider（provider: oneagent）
-Claude Code  不再出现 Not logged in
-```
-
-防复发的断言分两处：`test_install_contract.py` 的 `CredentialDeliveryTests` 遍历所有 auto Agent，要求每个在配置后都能从 env 文件或配置文件之一取到密钥；`test_release_policy.py` 要求 lock 里每个 auto Agent 都声明 `command` / `config_path` / `config_adapter` / `credential_delivery`，`native_env` 还必须给出变量名。原先的缺陷正是「没有任何测试问过密钥怎么到达 Agent」。
-
-
-
-让 Claude Code 也拿到 env 文件。lock 里为每个 auto Agent 声明它需要哪些环境变量，`install_many` 与 `activate_agent` 读该声明而不是硬编码集合。
-
-Claude Code 的 env 文件应导出 `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_MODEL` / `ANTHROPIC_SMALL_FAST_MODEL`，`_next_step` 相应改为先 source 再启动。`settings.json` 继续写（它承载非认证配置），但不再是认证的唯一途径。
-
-必须有一个测试断言「每个自动配置 Agent 都有可用的认证途径」，否则同类缺陷会再次静默通过。
-
-### 任务 2：让 lock 成为真正的唯一真源 — 已完成
-
-落实情况：`backups` 改为遍历 lock、按各 Agent 的 `config_path` 推导备份 glob，不再手写两条路径；`providers.py` 的 `provider_config_base` 改收推理协议（调用方传 `agent_protocol(adapter)`），两处 `"claude-code"` 字面量比较移除；`_require_prerequisites` 与 `status_payload` 的 Windows 门禁改读 `windows_prerequisites`。`test_release_policy.py` 新增 `LockIsTheSourceOfTruthTests`，遍历 lock 断言备份、Windows 门禁与协议判定都由声明驱动。
-
-把重复的三项改为读 lock：
-
-- `_next_step` 与 `_restart_hint` 用 `meta["command"]`，不再手写命令名。
-- `backups` 用 `meta["config_path"]` 推导备份 glob，不再手写路径。
-- `_require_prerequisites` 与 `status_payload` 读 `meta["windows_prerequisites"]`，不再判断 `agent_id == "claude-code"`。
-- `providers.py` 用 `agent_protocol(adapter)` 判断，不再比较 agent id。
-
-目标：新增 Agent 只需改 lock 加一个适配器函数。加一个测试遍历 lock，断言不存在只在 Python 里出现的 Agent 行为。
-
-### 任务 3：把「配置后能用」纳入验证 — 已完成
-
-落实情况：新增 `scripts/agent_config_adopted_check.py`。其中纯分类器 `classify_adoption` 判别「连接失败 = 配置已采用」与「认证/登录错误 = 配置未采用」，由 `test_rc_scripts.py` 用本轮 Codex 与 Claude Code 两个真实输出在常规 CI 离线覆盖；脚本本体把配置指向丢弃端口 `127.0.0.1:9`、用假 Key，自包含安装并实跑 Agent，无需任何真实 Key，已接入 `release-candidate.yml`（非 Windows）。这把发现本轮缺陷的那道「真实 Key 门槛」从该检查里移除了。
-
-`agent_e2e_smoke.py` 已经会实际调用两个 Agent，但它需要真实 Key，本轮缺陷就是在那道门槛之外发现的。补一个不需要 Key 的检查：把配置指向丢弃端口，断言 Agent 报的是连接失败而非认证/配置错误——这恰好能区分本轮两种结果，且能进常规 CI。
-
-## 4. 明确不做
-
-- 不改 `_write_agent_config` 的 adapter 分派。适配器是代码而非数据，五个函数写的是五种格式，这不是硬编码。
-- 不为 guide-only Agent 建配置或 env 文件。
-- 不扩展到另外三个 Agent 的实测。本轮范围是 Codex 与 Claude Code；但任务 1、2 的实现应当对五个都成立，因为它们要消除的正是「按 id 特判」。
 
-相关文档：[空白机器可用性验证计划](blank-machine-verification-plan.md)、[产品边界基线](product-boundary-baseline.md)。
+新增自动配置 Agent 时只需更新 `agents.lock.json`、增加对应 Go adapter 和测试，并更新前端生成 binding 需要的公共类型。
diff --git a/docs/config-discovery-plan.md b/docs/config-discovery-plan.md
index 6e105f25..fa3c9072 100644
--- a/docs/config-discovery-plan.md
+++ b/docs/config-discovery-plan.md
@@ -1,149 +1,19 @@
-# 读取用户既有 Agent 配置，与全链路验证环境
+# 读取用户既有 Agent 配置
 
-> **实施状态（2026-07-29）**：第 2 节全部落地。五个 `read_*_config` 加 `detect_agent_config`，`status_payload` 每个 auto Agent 增 `detected`；前端 `targetSummary` 统一显示逻辑，详情页在覆盖非 OneAgent 配置前预警。`tests/test_config_discovery.py`（21 用例）与 `tests/existing_config_test.sh`（fixture，已接入两个 cleanroom）。真机验证：本机 Codex / Claude Code / OpenCode 的真实配置此前全部显示「未配置」，现在各自端点与模型都能读出并标注来源。
->
-> 第 3 节的容器化 macOS 结论不变：硬件不支持，以 fixture 层替代。
+> 状态：已实施（2026-07-31）。Go `internal/config` 提供只读发现器，Wails status 和 CLI 共用；本文件记录行为而非旧实现路径。
 
-两个需求：检测不能只看环境、还要看各 Agent 实际配置成什么样；以及在容器里的 macOS 虚拟机中跑全链路。
+## 行为
 
-第二个需求在当前硬件上不成立，第 3 节给出证据和替代方案。第一个是真实缺口，已实测确认。
+每个 auto Agent 的 status 同时提供：
 
-## 1. 现状：OneAgent 看不见自己没写过的配置
+- OneAgent 自己的 binding（Provider、模型、更新时间）。
+- `detected`：从 Agent 实际配置文件读出的 base URL、模型、是否由 OneAgent 标记、解析错误（不包含 Key）。
 
-`status_payload()` 对每个 Agent 报四个字段，来源如下：
+支持 Codex TOML、Claude settings JSON、OpenCode/Kilo JSON、Aider env 脚本。读取只做行解析或 JSON/TOML 解析，绝不执行配置脚本、修正文件或返回凭据。坏文件只标记 `unreadable`，不会让整个 status 请求失败。Aider 无法可靠区分手写和 OneAgent 形态，因此 `managedByOneAgent` 保守为 false。
 
-| 字段 | 来源 | 问题 |
-| --- | --- | --- |
-| `installed` | `runtime.which(command)` | 无 |
-| `configured` | `path.exists()` | **只知道文件在，不知道里面是什么** |
-| `provider` / `model` / `baseUrl` | `~/.oneagent/agents/<id>.json` | **OneAgent 自己的记账，不是 Agent 的真实配置** |
+## 安全约束
 
-实测：手写一份 Codex 与 Claude Code 配置（模拟用户自己配过、或用别的工具配过），不建任何 OneAgent binding，然后读 status：
-
-```
-codex        configured=True  provider=None  model=None  baseUrl=None
-claude-code  configured=True  provider=None  model=None  baseUrl=None
-
-磁盘真实内容   codex  -> someone-else / gpt-5-mini / api.other-vendor.com
-              claude -> api.third-party.com / claude-x
-```
-
-**`configured=True` 但三个字段全是 `None`。** 界面因此只能显示「未配置」，而磁盘上明明有一份指向别处的配置。三个后果：
-
-- **总览说谎。** 用户看到「未配置」，实际有配置在生效。
-- **覆盖无预警。** 用户点「应用」会静默盖掉自己手写的 provider（备份有，但界面没提示即将覆盖什么）。
-- **产品定位打折。** [近期工作纪要](recent-work-summary.md) 说它要从「一次性工具」变成「长期管理设备上各个 Agent」，而管理的前提是先看得见。
-
-顺带一个更小的问题：`configured` 这个名字对 guide-only Agent 也返回 `path.exists()`，而我们从不为它们写配置——那个 `True` 的含义与 auto Agent 完全不同。
-
-## 2. 要做的：配置读取（inspect）
-
-方向是**每个适配器补一个反向函数**：现在有五个 `write_*_config` 把结构化字段翻译成各 Agent 的格式，加五个 `read_*_config` 把格式翻译回结构化字段。这与既有设计一致——适配器是代码而非数据（见 [配置链路审查](config-chain-audit.md) 第 4 节），所以反向也应是代码。
-
-### 2.1 数据形状
-
-`status_payload` 的每个 Agent 增一个 `detected` 对象，与 `provider`/`model`/`baseUrl`（OneAgent 记账）并列而不是替换：
-
-```python
-"detected": {
-    "baseUrl": "https://api.other-vendor.com/v1",
-    "model": "gpt-5-mini",
-    "managedByOneAgent": False,   # 配置里是否有 OneAgent 写的标记
-    "provider": None,             # 能反查到内置 Provider 则给 id，否则 None
-    "unreadable": None,           # 解析失败时给原因
-}
-```
-
-两者并列的理由：不一致本身就是要显示的信息。binding 说 PPIO 而磁盘说别的，意味着用户在 OneAgent 之外改过配置——这正是「长期管理」要告诉用户的事。
-
-`managedByOneAgent` 的判据是配置里的既有标记，不需要新增字段：Codex 看有没有 `[model_providers.oneagent]`，OpenCode/Kilo 看 `provider.oneagent`，Claude Code 看 `env` 里四个 `ANTHROPIC_*` 是否齐全。
-
-**Aider 是例外，恒为 `false`。** 计划原本写「看脚本里是否是我们的两行 export」，fixture 实测推翻了它：手写的 Aider 脚本与我们写的形态完全一样（都是两行 export），没有任何标记能区分。它的配置又在 `~/.oneagent/` 下——本来就是我们的目录。所以承认无法区分，而不是让一个猜测冒充判据。
-
-### 2.2 五个读取函数
-
-- `read_codex_config` —— TOML，取 `model_provider` 指向的那个 `[model_providers.*]` 的 `base_url`，以及顶层 `model`。注意**不读 `env_key` 指向的值**（那是密钥）。
-- `read_claude_config` —— JSON，取 `env` 里的 `ANTHROPIC_BASE_URL` 与 `ANTHROPIC_MODEL`。
-- `read_openai_compatible_config` —— JSON，取 `provider.<name>.options.baseURL` 与 `model`（形如 `oneagent/<model>`，要剥前缀）。OpenCode 与 Kilo 共用。
-- `read_aider_config` —— shell/PowerShell 脚本，取 `OPENAI_API_BASE`。这个要用行解析而非执行脚本。
-- 未知 adapter 一律返回 `unreadable`，不猜。
-
-### 2.3 硬性约束
-
-**绝不把读到的密钥放进响应。** 这是最需要小心的一点：五份配置里有三份含密钥明文（Claude 的 `ANTHROPIC_AUTH_TOKEN`、Aider 的 `OPENAI_API_KEY`，以及 OpenCode 若用户手填过 apiKey）。读取函数必须只提取 base URL 与 model，且：
-
-- `detected` 里没有任何密钥字段，连布尔的 `hasKey` 也先不加（想加要单独评估：它会泄漏「这台机器上有没有配过 Key」）。
-- 读取过程中的异常消息不得包含文件内容片段——`CONFIG_WRITE_FAILED` 现有的错误消息带路径不带内容，沿用同样做法。
-- 加一个测试：构造含 `sk-` 明文的配置，断言 `/api/status` 全文不含它。这类断言 `test_core.py` 已有先例（`test_api_key_reaches_only_the_designated_secret_files`）。
-
-**解析失败不能让 status 挂掉。** 一份被改坏的 TOML 现在会让整个 `/api/status` 500，从而整个界面白屏。每个读取函数必须自己吞掉解析异常并返回 `unreadable`，理由与 `write_*` 遇到坏配置时返回 `CONFIG_WRITE_FAILED` 而非静默覆盖一致——只是这里的失败必须是局部的。
-
-**只读，不改。** inspect 路径不得触发任何写入，包括不得「顺手修正」格式。
-
-### 2.4 界面
-
-`AgentManageRow` 与 `AgentDetailPage` 现在显示 binding。改为：
-
-- 有 binding 且与 detected 一致 → 照现在显示。
-- 有 detected 无 binding → 显示 detected，标注「检测到的配置（非 OneAgent 写入）」。
-- 两者不一致 → 显示 detected 为主，提示 binding 记录的值不同。
-- `unreadable` → 显示「配置无法解析」并给出路径，不显示猜测值。
-
-详情页的「应用」按钮在 detected 存在且非 OneAgent 管理时，应当说明即将覆盖什么。这是把「无预警覆盖」变成有预警。
-
-### 2.5 测试
-
-- 五个适配器各一组「写入→读回」往返用例，断言读回的 baseUrl 与 model 等于写入值。这条最有价值：它同时锁住两个方向。
-- 手写的、非 OneAgent 格式的配置能被读出正确值（就是第 1 节那个实测场景，固化下来）。
-- 坏配置返回 `unreadable` 且 `/api/status` 仍返回 200。
-- 密钥不出现在响应里。
-- guide-only Agent 不产生 `detected`。
-- `installer.py` 100% 分支、零 partial 的门禁不变。
-
-## 3. 关于「Docker 里的 macOS 虚拟机」
-
-**这台机器上不可行**，原因是硬件而非配置：
-
-```
-主机架构        arm64（Apple Silicon）
-kern.hv_support 1（主机支持虚拟化）
-容器内 /dev/kvm No such file or directory
-容器 x86 支持   有（用户态转译）
-```
-
-`sickcodes/docker-osx` 一类方案的原理是容器内 QEMU 加载 **x86_64** macOS 镜像，前提是 `/dev/kvm` 可用。两个条件都不满足：
-
-1. **Docker Desktop 的 LinuxKit VM 不暴露嵌套虚拟化**，容器里没有 `/dev/kvm`。这不是权限问题，是 Docker Desktop on macOS 的架构决定的。
-2. **arm64 主机上没有可用的 macOS 虚拟磁盘镜像。** Apple Silicon 版 macOS 只能通过 Apple 自己的 Virtualization.framework 跑，不能被 QEMU 当作 x86 客户机加载。容器里的 x86 支持是用户态二进制转译，跑不动一个内核。
-
-即使强行在 x86 主机上做，还有两个问题值得先说清：**Apple 许可证只允许在 Apple 硬件上虚拟化 macOS**，容器化 macOS 镜像的分发本身处在灰区——这与 [产品边界基线](product-boundary-baseline.md) 对分发合规的要求不一致，不适合成为项目的标准验证设施。
-
-### 替代方案：已有的两层，加一层缺口
-
-需求的实质是「全链路在干净 macOS 上可重复验证」。现有设施已经覆盖了大部分：
-
-| 层 | 设施 | 覆盖 |
-| --- | --- | --- |
-| Linux 断网容器 | `scripts/test_docker_cleanroom.sh` | 契约测试、`install.sh`、GUI 冒烟、浏览器 e2e、策略扫描 |
-| 真实 macOS | `tests/macos_cleanroom_test.sh` | 干净 HOME、权限、打包二进制、真实 HOME 零污染快照 |
-| 真实安装 | `tests/real_install_test.sh` | 真装两个 Agent、PATH、版本、双 registry |
-
-**真实缺口不是「缺一个 macOS 环境」，而是这三层都不覆盖「用户已有配置」这个起点。** 它们都从干净 HOME 开始，所以第 2 节要读的那种「外部写入的配置」在任何 cleanroom 里都不会出现。
-
-所以要加的是一层 fixture，而不是一个虚拟机：
-
-- 在 `tests/` 下建一组**既有配置样本**（手写风格的 Codex TOML、第三方 Claude settings、含额外用户字段的 OpenCode JSONC、坏格式各一份）。
-- macOS cleanroom 与容器 cleanroom 各增一个阶段：把样本放进干净 HOME，断言 status 能读出正确的 detected 值、坏样本报 `unreadable` 而非 500、写入后用户的额外字段仍在。
-- 这一层是离线纯文件操作，两个 cleanroom 都能跑，也能进常规 CI。
-
-如果确实需要一台干净 macOS 做人工验收，可行路径是本机的 Virtualization.framework（Tart、UTM 或 `macosvm`），而非 Docker。那属于本地开发环境搭建，不该进 CI——CI 里的 macOS 由 GitHub Actions 的 `macos-14` runner 提供，已经在用。
-
-## 4. 明确不做
-
-- **不为读取配置引入任何写入。** inspect 只读。
-- **不把密钥或其存在性放进 API 响应。** 只提取 base URL 与 model。
-- **不猜未知格式。** 未知 adapter 或解析失败一律 `unreadable`。
-- **不做容器化 macOS。** 硬件不支持，且分发合规不成立。
-- **不改 `configured` 字段的现有语义**（避免破坏前端契约），新增 `detected` 与之并列；若将来要收敛，另开一次改动。
-
-相关文档：[配置链路审查](config-chain-audit.md)、[空白机器可用性验证计划](blank-machine-verification-plan.md)、[产品边界基线](product-boundary-baseline.md)。
+- 检测响应不含 API Key、Token 或 Key 是否存在的推断。
+- 错误只包含路径和解析诊断，不回显文件内容。
+- 覆盖非 OneAgent 配置前，前端显示警告并保留备份。
+- guide-only Agent 不生成 `detected`。
diff --git a/docs/decisions/ADR-003-three-platform-python-core-and-release-policy.md b/docs/decisions/ADR-003-three-platform-python-core-and-release-policy.md
index 0d9c914c..2ce076aa 100644
--- a/docs/decisions/ADR-003-three-platform-python-core-and-release-policy.md
+++ b/docs/decisions/ADR-003-three-platform-python-core-and-release-policy.md
@@ -1,118 +1,29 @@
-# ADR-003：三平台 Python 安装核心与版本锁定发行策略
+# ADR-003：三平台运行时与版本锁定发行策略（已废弃）
 
-## Status
+> 状态：**Superseded**（2026-07-31）。当前实现和发行规则由 [ADR-007](ADR-007-wails-v3-go-migration.md)、[ADR-005](ADR-005-channel-neutral-distribution-and-compliance.md) 和 `cmd/oneagent-release` 定义。本文件只保留历史背景，不是安装或发布操作指南。
 
-Accepted
+## 历史背景
 
-## Date
+早期 OneAgent 使用跨平台脚本和 Python 标准库实现 Agent catalog、配置适配、安装编排和本地 HTTP GUI。该方案曾强调三平台路径、权限、锁定版本、npm/uv allowlist、完整错误码和 cleanroom 证据。
 
-2026-07-22
+这些产品约束仍然有效，但实现已经迁移为：
 
-## Scope Update
+- Go catalog、provider、install、config、profile、securefs 和 process 包。
+- `cmd/oneagent` 纯 Go CLI 与 `cmd/oneagent-desktop` Wails 应用。
+- React 通过生成的 Wails bindings 调用 Go service。
+- `cmd/oneagent-release` 生成原生 Wails/Go 包、manifest、SHA-256 和第三方 notices。
+- `cmd/oneagent-rc` 与 `cmd/oneagent-provider-smoke` 承担发行候选检查。
 
-Python 共用内核、版本锁定、配置适配和结构化错误决策继续有效。当前渠道分发范围和发行门禁已由 [ADR-005](ADR-005-channel-neutral-distribution-and-compliance.md) 更新，不再以四平台同时发布作为当前产品阶段门槛。
+## 仍保留的产品约束
 
-## Context
+- Agent 包不进入 OneAgent 发行包；安装只能来自 lock 声明的官方源或用户明确选择的 HTTPS 镜像。
+- 子进程使用参数数组、受控环境和超时；禁止 shell 拼接和未审查的下载管道。
+- API Key 不进入 profile、日志、URL、命令行、React 状态或发行附件。
+- 配置写入必须备份、原子替换并收紧 Unix mode/Windows ACL。
+- Codex、Claude Code 和 OpenAI-compatible Agent 按实际协议分别探测。
+- Wails Alpha 阶段只发布 `technical-preview-unsigned`；Stable 需要单独的签名、公证和原生验证证据。
+- Aider 是可选外部上游例外：用户选择安装时需要已有 Python 3.12，OneAgent 不捆绑或下载该运行时。
 
-OneAgent 的产品基线要求 macOS、Windows 和 Linux 在发布前分别验证，但早期实现以 Bash 安装脚本和浏览器 GUI 为中心，无法为 Windows 原生路径、ACL、PowerShell 环境文件和跨平台打包提供同一套行为契约。
+## 迁移记录
 
-Agent 的上游安装版本持续变化。默认安装 `latest` 会使测试、配置兼容性和发行包验收无法复现，也无法准确生成第三方许可证与版本清单。
-
-React 前端需要稳定的状态、错误和安装结果 API。如果前端迁移早于安装核心和 API 契约冻结，页面会固化尚未闭合的后端语义。
-
-## Decision
-
-### 平台与架构（内核兼容设计，不是当前分发门槛）
-
-- Python 核心保留 macOS、Windows 和 Linux 的路径、权限和前置条件适配设计；当前发行包只声明实际构建和验证过的目标环境。
-- 不以 macOS、Windows 和 Linux 同时构建或验收作为当前产品阶段门槛；每个实际发布的平台仍须在对应操作系统原生构建，并有 `ci.yml` cleanroom 作业或 Release Candidate 流程的验收证据。
-- 各平台最低目标：macOS 13+（arm64/x64）、Windows 10 22H2 / Windows 11（x64）、Ubuntu 22.04+ 或兼容 glibc 环境（x64）。产物声明的目标环境不得低于上述最低版本。
-- 检测、版本校验、前置条件、安装编排、备份、配置合并、权限和环境摘要统一由 Python 核心实现。
-- `scripts/install.sh` 和 `scripts/install.ps1` 只负责定位 Python 并转发参数；本地 GUI 直接调用同一个 Python 核心。
-- Windows 使用 `%USERPROFILE%` 对应的原生用户目录，不写 WSL HOME，不自动调用 `wsl.exe`。
-
-### Agent 范围
-
-自动配置范围固定为五个 Agent：
-
-1. Codex
-2. Claude Code
-3. OpenCode
-4. Kilo CLI
-5. Aider
-
-其他 catalog Agent 保持 `guide-only`。OneAgent 不猜测或修改没有稳定公开配置合约的私有状态文件。
-
-### 安装与版本
-
-- 默认安装版本来自受版本控制的 `agents.lock.json`。
-- 每个自动配置 Agent 必须显式声明包管理器、包名、版本、完整性信息（适用时）、版本检查命令、支持平台、配置适配器、官方来源和许可证地址；不能只依赖 Agent ID 的隐式分支。
-- 只允许 manifest 中声明的 npm 或 uv tool 安装命令，subprocess 必须使用参数数组且禁止 `shell=True`。Aider 使用隔离的 uv tool 环境，不调用系统级 pip。
-- `--latest` 是用户显式选择的高级选项，不进入默认流程、PR 测试或发行验收。
-- 缺少 npm、uv、Python 3.12、Git for Windows 等前置条件时返回 `PREREQUISITE_MISSING`。Aider 安装固定传入 `--no-python-downloads`，不自动安装语言运行时或 Git Bash。
-
-### 密钥与本地状态
-
-- API Key 只写入对应的本地密钥文件或 Agent 配置；Unix 目录使用 `0700`、文件使用 `0600`，Windows ACL 只允许当前用户和 SYSTEM。
-- 权限设置失败时配置失败，不静默降级。
-- Key 不进入命令行、URL、日志、环境摘要、React reducer、测试报告或遥测。
-- `~/.oneagent/profile.json` 只保存 schema version、Provider、Base URL、模型、Agent、配置模式和激活时间。
-
-### Provider 协议
-
-- PPIO/Novita 的 OpenAI-compatible base 用于模型列表、Chat Completions、OpenCode、Kilo CLI 和 Aider。
-- Claude Code 对内置 Provider 使用各自公开的 Anthropic-compatible base；Custom 显式覆盖由用户负责协议兼容。
-- Codex 当前配置使用 Responses 协议。Chat Completions 探测成功不能证明 Codex 可用，必须在 Release Candidate 中测试 `/v1/responses` 和真实 Codex 首次请求。
-- 如果某个内置 Provider 不支持 Agent 当前所需协议，该组合必须明确降级为不支持或 `guide-only`。V1 不通过本地协议网关隐藏兼容性缺口。
-
-### API 与前端门槛
-
-- `/api/status` 只做向后兼容的字段追加；错误响应保留 `error/message/status` 语义并增加稳定 `error_code` 与 `retryable`。
-- `/api/install` V1 保持同步，前端只显示不定进度和最终逐 Agent 结果。
-- 所有 POST 必须同时通过随机 HttpOnly 会话 Cookie 与 localhost Origin 校验。
-- React 七页流程只能建立在 Python 核心、三平台适配和 API contract tests 全绿的冻结契约上。
-
-### 发行
-
-- 默认发布源码 ZIP 与 PyInstaller onedir 压缩包，不发布单文件自解压版本。
-- 每个产物必须明确记录实际构建环境、架构和验证范围；未验证的平台不得出现在兼容性承诺中。
-- GitHub、官网、网盘和企业云盘只作为同一官方构建的镜像渠道，不维护渠道专属包体。
-- 未签名产物只能标记为 `technical-preview-unsigned`。
-- Stable 额外要求 macOS 签名/公证和 Windows Authenticode，由 `scripts/build_release.py` 对产物本身做签名验证强制（环境变量不构成证据）。该门槛未被任何决策取代；当前阶段只是不发布 Stable。
-- 每个产物必须附 SHA-256、锁定版本清单和第三方许可证清单。
-- `release-candidate.yml` 的定义门禁是真实验收：四平台真实安装五个锁定 Agent，并用受保护 Provider Key 执行真实协议冒烟。在 CI Secret 配置完成前它尚未运行；常规 CI 以包体完整性、临时 HOME 启动、许可证、secret 扫描和本地 Mock 流程为门禁。
-
-## Alternatives Considered
-
-### 继续扩展 Bash，并为 Windows 单独维护 PowerShell 实现
-
-- 优点：短期改动较少。
-- 缺点：核心逻辑会形成两套实现，备份、权限、错误码和配置合并容易漂移。
-- 结论：拒绝。
-
-### 先完成 React，再逐步替换后端
-
-- 优点：更早看到新界面。
-- 缺点：前端会依赖未冻结的安装语义，导致重复重构和错误状态映射。
-- 结论：拒绝。
-
-### 默认安装上游 latest
-
-- 优点：用户总能获得最新功能。
-- 缺点：测试不可复现，可能在无代码变化时产生安装回归，也无法准确审核许可证和版本。
-- 结论：拒绝；保留显式 `--latest`。
-
-### Electron 或 Tauri 桌面壳
-
-- 优点：更接近原生桌面分发。
-- 缺点：引入额外运行时、签名面和构建复杂度，当前本地浏览器 GUI 已能满足流程需求。
-- 结论：V1 不采用。
-
-## Consequences
-
-- 源码模式仍需要本机 Python；发布包通过 PyInstaller 携带运行时，不要求终端用户安装 Python。
-- 安装核心和测试规模增加，但三平台行为可由同一契约验证。
-- React 不直接执行命令或写配置，只消费本地 API。
-- 每次更新锁定 Agent 版本都必须同步验证真实安装、版本输出、许可证和发行清单。
-- 同一个模型 ID 跨 OpenAI、Anthropic 和 Responses 协议的可用性不能由 `/v1/models` 推断，必须进入 Provider/Agent 兼容性矩阵。
-- WSL 管理、自动更新、后台服务、统一网关和遥测需要单独 ADR。
+Python 实现、Python 测试、PyInstaller/wheel/setuptools 配置和相关工作流已删除。新的验收清单见 [Wails v3 迁移收尾计划](../wails-v3-migration-plan.md)。
diff --git a/docs/decisions/ADR-004-per-agent-protocol-verification.md b/docs/decisions/ADR-004-per-agent-protocol-verification.md
index d05ec6bc..137d220e 100644
--- a/docs/decisions/ADR-004-per-agent-protocol-verification.md
+++ b/docs/decisions/ADR-004-per-agent-protocol-verification.md
@@ -10,7 +10,7 @@ Accepted
 
 ## Context
 
-[ADR-003](ADR-003-three-platform-python-core-and-release-policy.md) 冻结了五个自动配置 Agent 与配置适配器映射，但连接测试始终只发一种请求：`POST <openai-base>/v1/chat/completions`。
+[ADR-003](ADR-003-three-platform-python-core-and-release-policy.md) 冻结了五个自动配置 Agent 与配置适配器映射，但早期连接测试始终只发一种请求：`POST <openai-base>/v1/chat/completions`。
 
 这与 Agent 配置后的真实行为不一致：
 
@@ -41,7 +41,7 @@ README 早已声明"同一个模型 ID 不一定同时兼容 OpenAI、Anthropic
 
 ### 协议映射
 
-每个 Agent 的推理协议由 `agents.lock.json` 的 `config_adapter` 推导，映射表位于 `oneagent/catalog.py`，与配置写入使用同一来源，避免两处漂移。未登记的适配器回退为 OpenAI-compatible。
+每个 Agent 的推理协议由 `agents.lock.json` 的 `config_adapter` 推导，映射表位于 `internal/catalog`，与配置写入使用同一来源，避免两处漂移。未登记的适配器回退为 OpenAI-compatible。
 
 ### 验证时机
 
diff --git a/docs/decisions/ADR-005-channel-neutral-distribution-and-compliance.md b/docs/decisions/ADR-005-channel-neutral-distribution-and-compliance.md
index 54261b20..2982d7c5 100644
--- a/docs/decisions/ADR-005-channel-neutral-distribution-and-compliance.md
+++ b/docs/decisions/ADR-005-channel-neutral-distribution-and-compliance.md
@@ -30,14 +30,14 @@ OneAgent 采用“一个官方构建、多个同包镜像”的分发模型：
 - 默认只分发 OneAgent 自有代码和完成许可证义务的运行依赖。
 - 不分发第三方 Agent 二进制，不把官方可下载等同于允许再分发。
 - Agent 安装继续采用官方源、授权镜像、用户手动安装和 `guide-only` 的降级顺序。
-- 不捆绑 Node.js、Python、Git Bash、VPN、代理、共享 Key 或第三方配置工具。
+- 不捆绑 Node.js、Git Bash、VPN、代理、共享 Key 或第三方配置工具；Aider 的 Python 3.12 仅是用户选择 Aider 时的外部上游前置条件。
 
 ### 当前发行范围
 
 - 当前目标是可直接下载和运行的技术预览二进制包。分渠道分发不要求四平台全部齐备，但每个实际发布的平台仍须在对应操作系统原生构建，并以 `ci.yml` 的 cleanroom 作业或 Release Candidate 流程作为平台验收证据。
 - 每个产物只声明其实际构建和验证过的目标环境，不对未构建环境作兼容承诺。
 - 平台签名、公证、商店分发和自动更新不属于当前阶段。
-- 未完成更高等级发行门禁前继续使用 `technical-preview-unsigned`，不使用 Stable 标签。Stable 门槛本身仍然有效：`scripts/build_release.py` 会对声明为 Stable 的产物执行产物级签名验证（macOS `codesign` / Windows Authenticode），签名工具链缺失时 fail-closed；当前阶段只是不发布 Stable。
+- 未完成更高等级发行门禁前继续使用 `technical-preview-unsigned`，不使用 Stable 标签。Stable 门槛本身仍然有效，并由 `cmd/oneagent-release` 的后续签名阶段对产物执行验证（macOS `codesign` / Windows Authenticode）；当前阶段只是不发布 Stable。
 
 ### 合规门禁
 
@@ -46,7 +46,7 @@ OneAgent 采用“一个官方构建、多个同包镜像”的分发模型：
 ## Relationship To Previous Decisions
 
 - ADR-002 的网络访问、共享 Key、第三方 Agent 和配置工具边界继续有效。
-- ADR-003 的 Python 共用内核、版本锁定和配置适配策略继续有效。
+- ADR-003 的版本锁定、配置适配和权限约束继续有效；其旧运行时实现已由 ADR-007 的 Go/Wails 路径取代。
 - ADR-003 中“四平台同时作为当前发行门槛”的部分被本 ADR 收窄：解除“四平台必须同时齐备”的耦合，不解除任何单平台的原生构建与验收要求；平台矩阵可以作为后续扩展，不再阻塞当前渠道分发目标。
 - ADR-004 的按 Agent 协议验证继续有效。
 
@@ -99,4 +99,3 @@ OneAgent 采用“一个官方构建、多个同包镜像”的分发模型：
 - 自动安装来源位于固定 allowlist。
 - 技术预览状态、目标环境和已知限制明确。
 - 渠道负责人、链接、上传时间和撤回状态可追溯。
-
diff --git a/docs/decisions/ADR-006-multi-profile-and-long-term-management.md b/docs/decisions/ADR-006-multi-profile-and-long-term-management.md
index 3aa5c37c..f1dde478 100644
--- a/docs/decisions/ADR-006-multi-profile-and-long-term-management.md
+++ b/docs/decisions/ADR-006-multi-profile-and-long-term-management.md
@@ -2,7 +2,7 @@
 
 ## Status
 
-Accepted
+Implemented
 
 ## Date
 
@@ -45,7 +45,7 @@ OneAgent 目前是一次性向导：激活完成即结束，`~/.oneagent/profile
 - 向导激活（`install_many` 收尾的 `write_profile`）变为"更新或创建当前激活 profile"：同一 `provider + model` 沿用原 id 并保留 `agent_ids` 合并语义，否则新建。
 - 切换 = 用另一组参数重写同一批配置文件，**完全复用现有写入链路**（`_write_agent_config` 分派 + `atomic_write` + 备份），不引入新的写入逻辑。
 - `POST /api/activate` 的响应必须携带逐 Agent 的**重启指引**（采纳 CC Switch 教训：Agent 不自动重载配置），而不是只返回"已切换"。
-- 新增端点一律复用 `server.py` 现有 POST 校验（Origin 白名单 + HttpOnly 会话 Cookie），不另开通道。Key 经请求体传入、只落 `secrets/`，与现有 `/api/install` 的安全姿态一致。
+- Profile 操作统一复用 Go `ProfileService` 和 `securefs` 写入边界，不新增 HTTP 通道。Key 只落 `secrets/`，binding 返回公开摘要。
 
 ### CLI
 
@@ -96,5 +96,5 @@ OneAgent 目前是一次性向导：激活完成即结束，`~/.oneagent/profile
 - `profile.json` schema 变更，迁移是唯一的数据风险点：备份先行 + 测试固定。
 - `status_payload` 增加 `profiles` / `activeProfile` 字段，必须同步 `frontend/src/types/api.ts`（传输契约规则）。
 - CC Switch 文档的推荐顺序需要调整：OneAgent 内置切换为主路径，CC Switch 作为可选下游。
-- 覆盖率门禁不变：`installer.py` 100% 分支、整体 ≥85%、前端 `src/api`/`src/state` ≥85%；新端点与迁移路径都要配测试。
+- Go profile/config tests、React state tests 和 Wails binding tests 覆盖新端点与迁移路径。
 - 备份回滚 UI、per-agent profile、`--wire-shell` 需要各自的后续评估，其中回滚 UI 需要新端点。
diff --git a/docs/decisions/ADR-006-public-site-and-generated-release-index.md b/docs/decisions/ADR-006-public-site-and-generated-release-index.md
index d4356ab5..cee19699 100644
--- a/docs/decisions/ADR-006-public-site-and-generated-release-index.md
+++ b/docs/decisions/ADR-006-public-site-and-generated-release-index.md
@@ -1,23 +1,23 @@
-# ADR-006：独立公开站与机器生成发行索引
+# ADR-006：独立公开站与 GitHub Release 事实源
 
-- 状态：Accepted
+- 状态：Accepted（2026-07-31 修订）
 - 日期：2026-07-28
 
 ## 背景
 
-OneAgent 的 React 前端是随本地 Launcher 打包的操作界面。公开下载、搜索内容、发行证据和企业服务需要静态可索引页面，两者的安全、缓存、路由和发布周期不同。手工维护下载页版本与哈希会产生事实漂移。
+OneAgent 的 React 前端是随本地 Wails Launcher 打包的操作界面。公开下载、搜索内容、发行证据和企业服务需要静态可索引页面，两者的安全、缓存、路由和发布周期不同。站点构建直接读取 Release API 和仓库 JSON，保持独立发布周期。
 
 ## 决策
 
 1. 在同一仓库维护独立 `site/` Astro 静态站，不把营销路由加入本地 Launcher。
-2. 平台 manifest 与 SHA256SUMS 保持构建事实源；人工渠道状态放入 `distribution/channels.json`。
-3. 通过 `scripts/build_release_index.py` 验证并生成公开 `/release-index.json`，下载页面只消费该数据。
-4. Agent 兼容目录由 `agents.lock.json` 生成只读投影；Provider 商业披露放在独立数据文件，不能影响 rank 或技术结论。
+2. App 工作流只创建 GitHub Release；站点工作流由站点变更、Release 发布或人工操作独立触发。
+3. 公开版本、发布日期、下载资产、大小和摘要只读取 GitHub Releases API，不读取本地 App 构建目录，也不维护手工回退版本。
+4. Agent 兼容目录直接读取 `agents.lock.json`；Provider 运行时端点和商业披露统一读取 `providers.lock.json`，商业字段不能影响 rank 或技术结论。
 5. 网站默认不加载客户端分析脚本；Launcher 保持默认无遥测。
 
 ## 后果
 
 - Launcher 无需为官网 SEO、域名或外部托管做重构。
-- 发布站点必须拿到受验证的原生 artifact 才能显示下载按钮。
-- GitHub Pages、自有对象存储或其他镜像可以更换，但同版本包体与 SHA-256 不得变化。
-- 网站新增独立 Node 依赖和 CI 作业；源代码包包含网站源码但不包含 `node_modules`、`site/dist` 或复制后的下载目录。
+- Draft 和本地构建不会出现在官网；只有已发布 GitHub Release 能产生版本和下载按钮。
+- GitHub Pages 发布不构建 App，App 发布也不构建或部署 Pages。
+- 网站只需要 Node 工具链；App 源代码包不再携带站点源码。
diff --git a/docs/decisions/ADR-007-wails-v3-go-migration.md b/docs/decisions/ADR-007-wails-v3-go-migration.md
new file mode 100644
index 00000000..86f42da7
--- /dev/null
+++ b/docs/decisions/ADR-007-wails-v3-go-migration.md
@@ -0,0 +1,44 @@
+# ADR-007: Wails v3 Desktop Shell and Go Core Migration
+
+- Status: Implemented (2026-07-31)
+- Date: 2026-07-30
+- Supersedes: the Python-core, localhost-HTTP and PyInstaller decisions in ADR-003 only
+
+## Context
+
+The migration plan called for a Wails v3 desktop shell, a transport-independent
+Go core, and a separate headless CLI. Wails v3 is still Alpha, so the shipped
+channel remains an unsigned technical preview.
+
+## Decision
+
+1. The migration line uses Go 1.26+ and pins Wails v3 to
+   `v3.0.0-beta.2` for the initial native spike. The matching CLI uses the
+   same module version. The browser runtime candidate is pinned separately to
+   `3.0.0-alpha2.117`, the version shipped by that Wails module and present in
+   the frontend lockfile used by the production bundle.
+2. `agents.lock.json` remains the only hand-edited Agent catalog source. The
+   root Go package embeds that file once, and `internal/catalog` parses the
+   embedded bytes for both the CLI and desktop shell.
+3. `internal/app`, `internal/catalog`, `internal/platform`,
+   `internal/errors`, and `internal/binding` are the shared production core.
+   The native Wails implementation is enabled explicitly with the `wails` build
+   tag, while the headless CLI remains dependency-free from Wails/GTK.
+4. The first Wails shell registers only `StatusService`, `ProviderService`,
+   `AgentService`, and `ProfileService`. It does not configure `Route` or
+   `RawMessageHandler`, and it does not open a business HTTP listener.
+5. The Go/Wails path is now the only production implementation. The old source,
+   tests, packaging metadata and release scripts were removed after the Go
+   fixtures, bindings, cleanrooms and release checks passed. Shell wrappers remain
+   only as thin CLI forwarding compatibility layers.
+
+## Consequences
+
+- The Go status/catalog path and the full release toolchain can be tested without
+  a Python installation.
+- Native Wails builds currently require the platform WebView toolchain and a
+  generated frontend bundle; the default `go test ./...` does not link either.
+- The desktop UI and headless CLI call the same Go use cases; there is no HTTP or
+  legacy runtime fallback.
+- Updating Wails or the runtime requires rerunning binding generation and the
+  four-target native spike before changing the pins.
diff --git a/docs/distribution-compliance-policy.md b/docs/distribution-compliance-policy.md
index 625af7c7..11028968 100644
--- a/docs/distribution-compliance-policy.md
+++ b/docs/distribution-compliance-policy.md
@@ -54,7 +54,7 @@ withdrawal_reason
 
 允许进入 OneAgent 发行包的内容：
 
-- OneAgent 自有代码、构建后的 React 静态资源和 Python 运行组件。
+- OneAgent 自有 Go 代码和构建后的 React 静态资源。
 - OneAgent 自有图标、文档和配置模板。
 - 许可证明确允许再分发，且已经完成对应义务的第三方依赖。
 - `agents.lock.json`、官方安装入口和手动配置说明。
@@ -68,7 +68,7 @@ withdrawal_reason
 以下内容不得进入二进制包、源码包、网盘附件、发行说明或自动化脚本：
 
 - 未获再分发授权的 Codex、Claude Code、Cursor、Kiro、OpenClaw、Hermes 或其他第三方 Agent 二进制。
-- 从 npm、pip、uv、GitHub 或官网下载后直接复制进包内，但没有完成许可证审查的软件。
+- 从 npm、uv、GitHub 或其他来源下载后直接复制进包内，但没有完成许可证审查的软件。
 - 修改、破解、补丁化或绕过签名的第三方软件。
 - VPN、代理、节点订阅、机场、专线或其他绕过网络限制的工具和配置。
 - 共享账号、共享 API Key、长期 Token、Cookie、验证码处理或批量注册工具。
@@ -93,7 +93,7 @@ Agent 获取顺序固定为：
 - 命令以参数数组执行，禁止 `shell=True` 和动态拼接 shell 命令。
 - 安装前显示软件名称、来源、版本和将执行的动作，并由用户确认。
 - API Key、Token 和账号信息不得出现在命令行参数中。
-- 不自动安装 Node.js、Python、Git Bash、VPN 或系统级网络组件。
+- 不自动安装 Node.js、Git、VPN 或系统级网络组件。Aider 的外部 Python 3.12 只在用户明确选择 Aider 时由上游安装流程自行要求，绝不进入 OneAgent 包体。
 - 不执行未经固定和审查的 `curl | bash`。
 
 官方来源不可达时，只能报告不可达并提供手动安装入口。OneAgent 不配置代理，不提供绕过网络限制的说明，也不把第三方二进制转存到网盘作为临时替代。
diff --git a/docs/frontend-component-redesign-plan.md b/docs/frontend-component-redesign-plan.md
index 690690cb..3c58c99a 100644
--- a/docs/frontend-component-redesign-plan.md
+++ b/docs/frontend-component-redesign-plan.md
@@ -1,255 +1,26 @@
-# OneAgent React 前端实现与发布门禁
+# React 前端实现与发布门禁（已实施）
 
-## 文档状态
+> 本文原为前端重构计划，现转为当前实现摘要。历史 PyInstaller、解释器测试和旧 HTTP 命令已删除。
 
-- 状态：React 七页 GUI、Python API、安全边界和本机浏览器验收已实现。
-- 更新日期：2026-07-27。
-- 本机验证：macOS arm64。
-- 门禁状态（按 [ADR-005](decisions/ADR-005-channel-neutral-distribution-and-compliance.md) 更新）：四平台目标系统 CI 已实现，但不再要求同时齐备；每个实际发布平台仍须原生构建并有 cleanroom 验收证据。仍未完成：五个真实 Agent 安装、PPIO/Novita 真实协议请求（`release-candidate.yml` 已定义但尚未运行）。macOS/Windows 签名属于仍然有效的 Stable 门槛，当前阶段不走 Stable。
-- 架构依据：[ADR-003](decisions/ADR-003-three-platform-python-core-and-release-policy.md)。
+## 当前实现
 
-本文不再描述尚未开始的 React 迁移，而是固定当前实现、组件边界、测试口径和后续发布条件。
+- React 19 + TypeScript + Vite 构建 `frontend/dist`。
+- 页面通过 `frontend/src/backend/wails.ts` 调用生成 bindings。
+- Vitest 覆盖 backend adapter、state、页面和安全字段。
+- Playwright 使用 Wails `server,e2e` build tag；生产桌面构建不使用 server。
+- `cmd/oneagent-release` 在打包前检查 source map、远程资源和 secret，并将 Go/Wails/React 版本写入 manifest。
 
-## 当前技术栈
-
-| 层 | 实现 | 锁定版本/约束 |
-| --- | --- | --- |
-| UI | React + TypeScript | React `19.2.8`，TypeScript `7.0.2` |
-| 构建 | Vite | `8.1.5`，生产 source map 关闭 |
-| 路由 | React Router Hash Router | `7.18.1` |
-| 状态 | `useReducer` + Context + secret ref | Key 不进入 reducer |
-| 图标 | `lucide-react` | `1.25.0`，不伪造 Agent Logo |
-| 单元测试 | Vitest + Testing Library | Vitest `4.1.10` |
-| E2E | Playwright Chromium | `1.61.1` |
-| 本地服务 | Python 3.12 标准库 HTTP Server | 仅监听 `127.0.0.1` |
-| 安装执行 | `oneagent.installer` | Bash/PowerShell/GUI 共用 |
-| 发行 | PyInstaller onedir | `6.21.0`，目标系统原生构建 |
-
-终端用户运行打包版不需要 Node.js 或系统 Python。源码入口要求 Python 3.12+；前端开发要求 Node.js 22。
-
-## 运行架构
-
-```mermaid
-flowchart LR
-    Browser["React Hash Router"] --> Client["Typed API Client"]
-    Client --> Server["Python localhost Server"]
-    Server --> Installer["Python Installer Core"]
-    Server --> Provider["Provider Probe / Models"]
-    Installer --> Files["Agent Config / Backup / Profile"]
-    Installer --> PackageManager["Allowlisted npm / uv tool"]
-```
-
-职责边界：
-
-- React 只维护流程、表单、非敏感状态和最终结果。
-- API Key 只存在于密码输入 DOM、`useRef` 和当前请求体中。
-- Python 负责输入校验、Provider URL、安装、备份、配置合并、权限、脱敏和 profile。
-- Bash 与 PowerShell 只做 Python 版本检查和参数转发。
-- guide-only Agent 不进入自动安装和私有配置适配器。
-
-## 实际目录结构
-
-```text
-frontend/
-  index.html
-  package.json
-  package-lock.json
-  vite.config.ts
-  playwright.config.ts
-  e2e/
-    wizard.spec.ts
-  src/
-    main.tsx
-    App.tsx
-    api/
-      client.ts
-      client.test.ts
-    components/
-      AppWindow.tsx
-      NavigationSidebar.tsx
-      PageScaffold.tsx
-      SetupStepper.tsx
-      AgentRow.tsx
-      ChoiceRow.tsx
-      ProviderSegment.tsx
-      SecureKeyField.tsx
-      ConnectionStatus.tsx
-      ModelPicker.tsx
-      ReviewGroup.tsx
-      AgentProgressRow.tsx
-      LogDisclosure.tsx
-      EnvironmentSummary.tsx
-      StatusBadge.tsx
-    pages/
-      AgentSelectionPage.tsx
-      ConfigModePage.tsx
-      ProviderKeyPage.tsx
-      ModelSelectionPage.tsx
-      ReviewPage.tsx
-      ActivationPage.tsx
-      EnvironmentOverviewPage.tsx
-    state/
-      WizardContext.tsx
-      wizardReducer.ts
-      *.test.tsx
-    styles/
-      tokens.css
-      base.css
-      app.css
-    types/
-      api.ts
-```
-
-组件按职责拆分，七个页面没有重新合并进单一表单组件。路由守卫会阻止跳过 Agent、配置方式或模型选择的非法导航。
-
-## 页面与状态
-
-| 页面 | 主要组件 | 关键规则 |
-| --- | --- | --- |
-| Agent | `AgentRow`、分类折叠、安装开关 | Agent 多选；至少一个；展示 installed/configured/canInstall |
-| 配置方式 | `ChoiceRow` | Provider 模式或 existing-account；后者跳过步骤 3、4 |
-| Provider/Key | `ProviderSegment`、`SecureKeyField`、`ConnectionStatus` | PPIO/Novita/Custom；注册入口；Key 不持久化 |
-| 模型 | `ModelPicker` | `/v1/models` 成功选首项；失败回退手动输入 |
-| 确认 | `ReviewGroup` | 展示实际路径、备份、Provider、模型和 guide-only 项 |
-| 执行 | `AgentProgressRow`、`LogDisclosure` | 同步请求显示不定进度；按 Agent 最终状态；失败项单独重试 |
-| 总览 | `EnvironmentSummary` | 从无 Key 的 profile 恢复 Provider、模型和 Agent 摘要 |
-
-`WizardState` 只保存：Agent、配置方式、Provider ID、Custom URL、是否存在 Key、模型、连接状态、模型列表和安装结果。它不保存 Key 内容。
-
-单 Agent 重试通过 `profile_agents` 把完整选择集合传给 Python，避免重试成功后覆盖之前已完成 Agent 的环境摘要。
-
-## 视觉与响应式
-
-- 浅色 Native Utility Split View；标题栏 52px，桌面侧栏 232px，底部操作区 64px。
-- 页面背景 `#F5F5F7`，主表面 `#FFFFFF`，系统蓝 `#007AFF`，成功绿 `#34C759`。
-- 控件圆角 6px，分组 8px，窗口 12px；不使用营销 Hero、装饰渐变球或卡片堆叠。
-- 字体使用系统字体栈，`letter-spacing: 0`，字号不随 viewport 宽度缩放。
-- 日志默认折叠，只有展开后使用深色代码材质。
-- 支持 `prefers-reduced-motion` 和可见键盘焦点。
-
-验收 viewport：
-
-| Viewport | 结果 |
-| --- | --- |
-| 1440×900 | 七页通过，无横向溢出 |
-| 1280×800 | 七页通过，无横向溢出 |
-| 1024×720 | 七页通过，侧栏收窄，主内容独立滚动 |
-
-当前不提供手机布局，最低支持窗口为 1024×720。
-
-## API 与本地安全边界
-
-- `GET /api/status`：无需会话，返回 `apiVersion`、平台、能力、catalog、路径和可选 environment。
-- `POST /api/probe`：Chat Completions 最小请求。
-- `POST /api/models`：模型列表和手动输入回退。
-- `POST /api/install`：同步执行，返回 per-agent result。
-- `POST /api/open-register`：仅允许 PPIO/Novita 和已知 Agent ID。
-
-首页设置随机 HttpOnly、SameSite=Strict Cookie，Path 限定 `/api`。所有 POST 必须同时满足：
-
-1. Cookie 与当前 Server token 一致。
-2. `Origin` 为当前端口的 `127.0.0.1` 或 `localhost`。
-3. JSON body 不超过 64 KiB，字段类型严格匹配。
-
-静态服务：
-
-- 路径先 URL decode、规范化并验证仍位于 `frontend/dist`。
-- 拒绝 `..`、NUL、目录列表和未知 MIME。
-- `index.html` 为 `no-store`；Vite hash asset 为一年 immutable cache。
-- CSP 只允许同源脚本、样式、字体和连接；无 CDN、远程字体或内联脚本。
-- 构建缺失时返回本地 503 提示，不从互联网下载资源。
-
-## 密钥与文件系统
-
-- Key 不进入 URL、命令行、日志、profile、Reducer、localStorage/sessionStorage、截图文件名或遥测。
-- React 完成成功激活后清空 secret ref；日志显示前再次执行当前 Key 精确替换。
-- Unix 私有目录 `0700`，密钥目标、临时文件和备份 `0600`。
-- Windows 对目录、临时文件、目标和 secret backup 重置 ACL、关闭继承，仅授予当前用户和 SYSTEM。
-- ACL 或 mode 设置失败时，临时密钥在发布前删除；无法清理会返回 `CONFIG_WRITE_FAILED`。
-- `profile.json` 只保存 schema、Provider、Base URL、模型、配置模式、Agent ID 和激活时间。
-
-## Provider 与 Agent 协议
-
-- OpenCode、Kilo CLI、Aider 使用 OpenAI-compatible base。
-- Claude Code 对 PPIO/Novita 使用各自 `/anthropic` base；Custom 显式覆盖由用户负责协议兼容。
-- Codex `wire_api` 使用 Responses。PPIO/Novita 的 Responses 支持必须由 RC 真实 Key 测试确认，不能由 Chat Completions 探测替代。
-- 单一模型 ID 跨 OpenAI、Anthropic、Responses 的兼容性不是既定事实，发布验收必须启动真实 Agent 做首次请求。
-
-## 自动测试现状
-
-本机当前基线：
-
-- Python：63 项测试，整体分支覆盖 93%；`installer.py` 为 100% 分支覆盖，Windows 真实 ACL 测试在非 Windows 本机跳过。
-- React：14 项单元测试；状态/API 层分支覆盖 85%。
-- Playwright：6 项 E2E。
-- 完整七页：三个 viewport。
-- existing-account 跳过路径：通过。
-- 部分失败与单 Agent 重试：通过。
-- 浏览器存储保持空，sentinel Key 在激活后从 DOM 消失。
-- Bash CLI 和 GUI smoke：纳入最终回归。
-
-Vitest 只收集 `src/**/*.test.{ts,tsx}`；`frontend/e2e` 只由 Playwright 执行，避免测试运行器交叉加载。
-
-## CI 与发行
-
-普通 CI 矩阵：
-
-- `macos-15`：macOS arm64。
-- `macos-15-intel`：macOS x64。
-- `windows-2022`：Windows x64。
-- `ubuntu-22.04`：Linux x64。
-
-每个平台执行 Python contract、React coverage、生产构建和 Chromium E2E。Windows 额外执行 PowerShell wrapper 和真实 ACL 测试；Unix 执行 Bash/GUI 兼容测试。
-
-技术预览工作流在目标系统构建 PyInstaller onedir，运行冻结 CLI smoke，并校验：
-
-- 无 source map、`node_modules`、`output/`、coverage、Playwright 产物或 Agent 二进制。
-- 无可识别 Key 或 Authorization secret。
-- 包内有 lock manifest 和第三方许可证清单。
-- 外部 release manifest、SHA-256 和 artifact size 与真实文件一致。
-
-## 剩余 Release Candidate 门禁
-
-以下项目不能在当前 macOS arm64 本机模拟为完成。按 [ADR-005](decisions/ADR-005-channel-neutral-distribution-and-compliance.md)，四平台不再要求同时齐备——每个实际发布的平台须满足适用于它的条目：
-
-1. 每个实际发布的平台在对应操作系统原生生成并启动 onedir 产物。
-2. 五个 Agent 在已发布平台从官方源安装锁定版本，并执行真实 `--version`（`release-candidate.yml` 已定义，CI Secret 未配置，尚未运行）。
-3. Windows 使用空格路径、Unicode 用户名和真实 ACL 完成配置写入（仅在发布 Windows 产物时要求）。
-4. PPIO、Novita 使用受保护低权限 Key 调用 `/v1/models`、最小 Chat Completions、Anthropic Messages 和 Codex Responses（尚未运行，见 README“仍未取得证据的部分”）。
-5. 用生成配置启动五个真实 Agent，验证所选模型完成首次最小请求。
-6. 发行 ZIP、manifest、SHA-256、许可证和 secret scan 全部通过。
-7. 提升到 Stable 时额外完成 macOS 公证和 Windows Authenticode（`scripts/build_release.py` 产物级强制；当前阶段不走 Stable）。
-
-如果 PPIO 或 Novita 不支持 Codex 当前要求的 Responses 协议，必须在发布前把该 Agent/Provider 组合降级为明确的不支持或 guide-only；不得通过未批准的本地协议网关掩盖问题。
-
-开发期间允许使用 `apiproxy` 档案和 `openai/gpt-5.6-terra` 做 OpenAI、Anthropic、Responses 三协议的本地脚本预检，但它只验证测试工具链，不计入 PPIO/Novita 正式 RC 结果。`openai/gpt-5.6-luna` 只支持两类协议，不用于三协议统一预检。
-
-## 开发命令
+## 本地门禁
 
 ```bash
 cd frontend
 npm ci
 npm run test:coverage
 npm run build
-npm run e2e
+npm run test:e2e
+cd ..
+go run ./cmd/oneagent-release build --channel technical-preview-unsigned --skip-frontend
+go run ./cmd/oneagent-release check release
 ```
 
-```bash
-python3.12 -m coverage run --branch -m unittest \
-  tests.test_core tests.test_cli tests.test_server \
-  tests.test_release_policy tests.test_edge_cases tests.test_rc_scripts
-python3.12 -m coverage report --fail-under=85
-bash tests/install_test.sh
-python3.12 tests/gui_smoke_test.py
-```
-
-```bash
-python3.12 scripts/build_release.py --channel technical-preview-unsigned --source
-python3.12 scripts/check_release.py release
-```
-
-## 完成定义
-
-React 实现本身已经达到功能完成条件：七页、路由守卫、跳过配置、模型回退、部分失败、单 Agent 重试、环境摘要、三 viewport 和 secret ref 均已落地。
-
-产品发行仍受门禁约束：每个实际发布平台须原生构建并有 cleanroom 验收证据，真实 Agent 与真实 Provider 协议验收须按上文 RC 门禁执行。从 `technical-preview-unsigned` 提升到 Stable 还须满足平台签名条件（macOS 公证、Windows Authenticode）。四平台不要求同时齐备（[ADR-005](decisions/ADR-005-channel-neutral-distribution-and-compliance.md)）。
+Wails Alpha 阶段只允许 `technical-preview-unsigned`。真实 Agent/Provider 验收由 `cmd/oneagent-rc`、`cmd/oneagent-provider-smoke` 和对应 cleanroom 负责。
diff --git a/docs/frontend-management-console-plan.md b/docs/frontend-management-console-plan.md
index 5a400e58..0cca2020 100644
--- a/docs/frontend-management-console-plan.md
+++ b/docs/frontend-management-console-plan.md
@@ -1,182 +1,24 @@
-# 前端管理控制台改造计划
+# 前端管理控制台改造计划（已实施）
 
-把「跑完一次向导就结束」的界面改成能长期使用的管理控制台。
+> 状态：已实施（2026-07-31）。React 管理页面通过 Wails bindings 使用 Go profile/config/status 用例。
 
-**已完成**：首屏减负（`a55f597`）。总览首屏非内容占用从 55% 降到 23%，Agent 列表起始位置从 y=470 提到 197，五个 Agent 完整落在首屏。
+## 已交付
 
-**本计划涵盖余下四项**：Agent 品牌图标、侧边栏可用性与两个新页面、配置独立成页、视觉规范收敛。
+- 首屏环境总览、Agent 行式管理、Provider 和 Profile 页面。
+- Agent 详情页支持单 Agent 激活、Claude fast model 和配置发现警告。
+- Key 不进入 reducer、浏览器存储或 binding 公开摘要；仅在用户主动打开 Provider 编辑/配置表单时通过本机 binding 读入密码字段。
+- 生成的 `frontend/bindings` 是后端 DTO 的唯一类型来源。
+- Wails server/e2e fake runner 覆盖导航、重试、错误 cause 和临时 HOME；生产构建不使用 server tag。
 
-范围限于 `frontend/`，不改 Python 内核，唯一的后端改动是修一处已发现的契约泄漏（见 0.4）。
+## 当前验证
 
-## 0. 先确认的四个事实
+```bash
+cd frontend
+npm run test:coverage
+npm run build
+npm run test:e2e
+cd ..
+go test ./internal/app ./internal/profile ./internal/binding
+```
 
-**0.1 官方图标覆盖不全。** simple-icons（CC0）有 `claude`、`anthropic`、`opencode`、`cursor`，但 **Codex（openai）、Aider、Kilo 均为 404**。CC Switch 也只自带 `chatgpt.svg` 与 `claude.svg` 两个文件——它只管两个 Agent，我们有五个。因此采用**官方 + 自绘补齐**的混合方案（已确认）。
-
-**0.2 禁止 CDN。** `CLAUDE.md:72` 规定前端产物不得含 CDN 或远程字体引用，`cdn.simpleicons.org` 不可引用，图标必须内联进 bundle。也不装 `simple-icons` 依赖——为两三个图标引入整包不合理，只取所需 path 内联并注明来源与 CC0。
-
-**0.3 商标与 CC0 是两件事。** CC0 只覆盖 SVG 文件本身，不覆盖商标权。在自己 UI 内标示「这一行是哪个 Agent」属指示性使用；不得将第三方 logo 用作 OneAgent 的产品视觉资产、应用图标或营销素材。统一以 `currentColor` 单色渲染而非品牌色，既统一风格，也回避商标着色问题——这正是 macOS 的处理方式：形状各异，容器与尺寸一致。
-
-**0.4 已发现一处契约泄漏（需修）。** `installer.py:1348` 把 `PROVIDERS` 常量整体写入 `status_payload`，导致上一轮新增的内部字段 `fallback_probe_model` 泄漏到 `/api/status`，而 `types/api.ts:78` 的类型定义并不包含它。这是探测模型改造引入的漂移。修法：`status_payload` 只投影 `name`/`home`/`base_url`/`anthropic_base_url` 四个公开字段，并补一个测试断言响应中不含 `fallback_probe_model`。
-
-**0.5 没有深色模式。** 三个样式文件里 `prefers-color-scheme` 出现 0 次。本次**不新增**深色模式——那是独立的一项工作，混进来会让每条视觉调整都要验两套配色。计划中所有颜色沿用现有亮色 token。
-
-## 1. Agent 图标
-
-### 实现
-
-新增 `frontend/src/components/icons/agents.tsx`，按 Agent ID 映射到图标组件：
-
-| Agent | 来源 |
-| --- | --- |
-| Claude Code | simple-icons `claude`（官方，CC0） |
-| OpenCode | simple-icons `opencode`（官方，CC0） |
-| Cursor 及其他 guide-only | simple-icons 对应条目，有则用 |
-| Codex | 自绘 |
-| Aider | 自绘 |
-| Kilo CLI | 自绘 |
-
-未知 ID 回退到 lucide `Bot`，保证新增 Agent 不会渲染空白。
-
-### 统一规范
-
-- 视图框统一 `24×24`；渲染 `18`（列表）/`20`（详情页）。
-- 单色 `currentColor`。官方图标多为实心填充，自绘为线条，两者视觉重量对齐的手段是：实心图标降到 `0.85` 不透明度，线条图标笔画宽 `1.8`（与 lucide 一致）。
-- 复用现有 `.agent-icon` 容器（38×38 圆角方块）。
-
-### 文字与可访问性
-
-图标**替换**当前按 group 区分的通用图标（现在五个 auto Agent 共用一个 `Code2`，毫无辨识度）。Agent 名称**保留**为主标题——删掉名称会牺牲可访问性与可搜索性。图标 `aria-hidden`，容器加 `title` 提供悬停说明，内容是该 Agent 的一句话定位，不重复名称。
-
-## 2. 侧边栏与两个新页面
-
-### Bug 根因
-
-`NavigationSidebar` 把 `/setup/provider` 和 `/setup/review` 当作独立页面，但它们是受 `SetupGuard` 保护的**向导步骤**：未选 Agent 时守卫重定向回 `/setup/agents`，所以点击像是没反应。这不是样式问题，是把流程步骤误当成了导航目的地。
-
-### 新的导航结构
-
-| 项 | 路由 | 内容 |
-| --- | --- | --- |
-| 环境总览 | `/overview` | 已有，Agent 列表 |
-| Provider | `/providers` | **新增** |
-| 配置模板 | `/profiles` | **新增** |
-
-向导（`/setup/*`）从侧边栏移除，仅由「激活环境」主按钮与首次运行进入。原「Agent」项指向总览，与「环境总览」重复，删除。
-
-### `/providers`
-
-每个内置 Provider 一行：名称、OpenAI-compatible base URL、Anthropic-compatible base URL（若有）、**正在使用它的 Agent 列表**（由各 Agent 绑定反查，这是 per-agent 之后才有意义的信息）、注册页链接。
-
-底部一个自定义 Provider 说明块，指出 Custom 由用户自行保证协议兼容——这条约束已在 ADR-003，界面应当复述。
-
-数据全部来自 `status.providers` 与 `status.agents[*].provider`，无需新 API。
-
-### `/profiles`
-
-`profiles/` 模板的可视化管理：模板名、Provider、模型、`hasKey` 标记、创建时间、适用 Agent。操作为「应用到某个 Agent」和「删除」。
-
-**安全约束**：模板可携带 Key，页面只能显示 `hasKey` 布尔，**绝不回显 Key 本身**。应用模板时 Key 由后端从 `secrets/` 读取（`--profile` 已有此能力），前端不接触。
-
-空态给「从现有 Agent 配置创建模板」的入口——比让用户从零填表更符合真实使用顺序。
-
-删除模板需要确认，且要说明删除不会改变已按该模板配置好的 Agent（模板只是模板）。
-
-## 3. 配置独立成页
-
-现在点「改配置」在卡片内展开面板，导致列表被撑长、多个面板可同时展开、状态散落在各行。
-
-### 路由与拆分
-
-新增 `/agents/:agentId`。总览的「改配置」改为跳转；整行可点击进入。
-
-`AgentManageRow` 退化为**纯展示行**：图标、名称、当前指向、版本、状态徽章。移除内联面板、probe 状态与 apply 逻辑。
-
-### 详情页
-
-- **头部**：图标、名称、当前 Provider 与模型、版本状态、返回总览。
-- **配置区**：Provider 分段、Base URL（custom 时）、模型、API Key、测试连接、应用。
-- **信息区**（详情页才有空间放的东西）：配置文件路径、凭据文件路径、是否有备份、最后更新时间。这些目前无处可去。
-- **应用结果**：重启指引与启动命令。
-
-### 必须随代码一起搬走的四条行为约束
-
-它们都有测试保护，平移时让测试跟着搬，不要删掉重写：
-
-1. 探测通过才能应用（防止错误 Key 写入配置）。
-2. 改动 Key 作废上次探测结论。
-3. 应用后显示重启指引（Agent 启动时读配置，不说等于让用户以为失败）。
-4. 应用后清空 Key 输入框（需 remount `SecureKeyField`，它按设计从内部 state 回显）。
-
-### 收益
-
-列表长度恒定；一次只有一个配置上下文；详情页容得下版本、备份、路径等信息。
-
-## 4. 视觉规范收敛
-
-现有 `tokens.css` 已是 macOS 风格（`#1d1d1f` 文字、`#007aff` 强调、`rgba(60,60,67,*)` 分隔线），继续沿用，不引入新色板。
-
-### 字号收敛
-
-实测现有 8 级：11px×14、12px×13、13px×9、14px×4、15px×2、16px、23px、26px。收敛到四级：
-
-| 级别 | 用途 |
-| --- | --- |
-| 11px | 辅助信息、路径、时间戳 |
-| 13px | 正文、列表项标题 |
-| 16px | 分区标题 |
-| 23px | 页面标题 |
-
-12px 合并进 13px，14/15px 合并进 13 或 16，26px 归并到 23px。
-
-### 层级只用一种手段
-
-现在 `.agent-manage-row` 同时用了边框、白底、阴影三重区分（`app.css:937`）。改为**只靠留白与分隔线**：卡片去掉边框与阴影，行间用 1px 分隔线，容器统一白底。悬停时才给极轻的底色变化。
-
-### 其余规则
-
-- **一屏一个主操作**：详情页只有「应用」是 primary，其余 secondary 或纯文字按钮。
-- **状态色只用于状态本身**，不作装饰；成功态用完即隐，不常驻（这正是首屏减负的原则，推广到全局）。
-- **动效**只保留 ≤150ms 的 opacity 与 transform 过渡，不做位移动画。
-- **触感一致**：所有可点区域最小高度 28px，圆角统一走 `--radius-control` / `--radius-panel`。
-
-## 5. 测试先行
-
-按既有约定，每步先写测试。
-
-**单元（vitest）**
-- `icons/agents.test.tsx`：五个 auto Agent 均有映射；未知 ID 回退；图标 `aria-hidden`。
-- `AgentManageRow.test.tsx`：改造为展示行——断言不再渲染表单控件；点击触发导航。
-- `AgentDetailPage.test.tsx`：平移第 3 节那四条约束。
-- `ProvidersPage.test.tsx`：某 Provider 下正确列出使用它的 Agent；无 Agent 使用时的表述。
-- `ProfilesPage.test.tsx`：列表、空态、**Key 不出现在 DOM 与浏览器存储**、删除需确认。
-
-**契约（Python）**
-- `test_server.py`：断言 `/api/status` 的 providers 不含 `fallback_probe_model`（0.4 的回归防护）。
-
-**e2e（Playwright）**
-- 侧边栏三项逐一点击，URL 与标题正确——直接覆盖第 2 节的 bug。
-- 总览进详情，改配置后返回总览看到新指向。
-- 列表长度不因操作而改变（第 3 节的动机）。
-- 三视口无横向溢出（沿用 `expectNoHorizontalOverflow`）。
-- 首屏预算测试已存在，保持通过。
-
-覆盖率门禁不变：`src/api`、`src/state` ≥85%；Python 整体 ≥85%，`installer.py` 100% 分支。
-
-## 6. 实施顺序
-
-| 步 | 内容 | 截图确认 |
-| --- | --- | --- |
-| 1 | 契约泄漏修复（0.4）+ 图标集 | 是 |
-| 2 | 侧边栏修复 + `/providers` + `/profiles` | 是 |
-| 3 | `/agents/:agentId` 详情页，`AgentManageRow` 瘦身 | 是 |
-| 4 | 视觉规范收敛（字号、层级、动效） | 是 |
-
-每步独立提交，跑该步相关测试加 `npm run build`；每步结束截图确认后再推进下一步。第 1 步的两项虽都不大，但都是独立可验证的前置工作，合并为一次提交。
-
-## 7. 风险
-
-- **第 3 步动的是刚落地的 `AgentManageRow`**，四条行为约束必须随测试一起搬移，这是本计划最容易丢东西的地方。
-- **第 2 步会影响既有 e2e**：`wizard.spec.ts` 有从侧边栏进入向导步骤的路径，需同步更新。上一轮移除横幅时已因类似原因让 4 个 e2e 变红，改断言的表达而非删除断言。
-- **第 4 步是大面积样式改动**，回归靠三视口无溢出测试与截图，不靠肉眼扫一遍。
-- **`/profiles` 涉及 Key**，见第 2 节安全约束。
-- 新增图标逐个确认许可，见 0.3。
+新增页面或字段必须先更新 Go DTO 和 binding，再更新 React adapter、state 和测试。旧 HTTP、Cookie/Origin 和解释器契约不再扩展。
diff --git a/docs/mvp-agent-installer-plan.md b/docs/mvp-agent-installer-plan.md
index 4bd8693f..b5debd74 100644
--- a/docs/mvp-agent-installer-plan.md
+++ b/docs/mvp-agent-installer-plan.md
@@ -1,207 +1,12 @@
-# 多页绿色启动器 MVP 计划
+# MVP Agent Installer 计划（已废弃）
 
-## 目标
+> 状态：**Superseded**（2026-07-31）。本文件记录最初的本地 HTTP/Python 原型，不能作为当前操作指南。当前入口请看 [README](../README.md) 和 [Wails 迁移收尾计划](wails-v3-migration-plan.md)。
 
-做出最小可用的绿色启动器：不重新分发 Agent 包体，用一个本地浏览器多页向导引导用户检测、安装和配置常用 Agent。
+早期原型使用标准库 HTTP GUI、单 Agent CLI 和脚本式配置写入。该原型已由以下实现替代：
 
-MVP 的成功标准是：新用户打开本地 GUI 后，可以选择一个或多个 Agent，决定是否配置模型服务，完成 API Key 与模型 ID 初始化，并看到下一步启动命令。
+- Wails desktop：`cmd/oneagent-desktop`
+- headless CLI：`cmd/oneagent`
+- Go services/use cases：`internal/app`
+- React bindings：`frontend/bindings`
 
-当前实现入口：
-
-- GUI 启动器：[scripts/gui.py](/Users/ppio/Documents/OneAgent/scripts/gui.py)
-- CLI 安装内核：[scripts/install.sh](/Users/ppio/Documents/OneAgent/scripts/install.sh)
-- CLI 测试：[tests/install_test.sh](/Users/ppio/Documents/OneAgent/tests/install_test.sh)
-- GUI 冒烟测试：[tests/gui_smoke_test.py](/Users/ppio/Documents/OneAgent/tests/gui_smoke_test.py)
-- 使用说明：[README.md](/Users/ppio/Documents/OneAgent/README.md)
-
-## 产品边界
-
-- 这是绿色启动器，不是 Agent 包体合集。
-- 不打包、不修改、不重新分发 Claude Code 或 Codex。
-- 不打包、不修改、不重新分发任何上游 Agent。
-- 缺少 Agent 时默认只提示官方安装命令。
-- 用户显式选择后，才对 allowlist 内 CLI Agent 调用包管理器安装。
-- 模型服务配置可跳过，跳过时不要求 API Key，也不写 `~/.oneagent/env`。
-- 默认推荐 PPIO 和 Novita，同时保留 Custom OpenAI-compatible base URL。
-- API Key 只通过本地页面输入或环境变量传给子进程，不放进 GUI 日志和命令行参数。
-- OpenClaw、Hermes、Cursor、Kiro、Gemini CLI 和 IDE 扩展类 Agent 第一版只做官方引导，不写私有配置。
-
-## MVP 流程
-
-1. 用户运行 `python3 scripts/gui.py`。
-2. 本地服务只监听 `127.0.0.1`，并打开浏览器页面。
-3. 用户从分组目录里多选要处理的 Agent。
-4. 页面展示每个 Agent 的本机安装状态。
-5. 用户选择配置模型服务，或跳过配置并使用官方账号/已有本地配置。
-6. 如果跳过配置，直接进入确认页，只做 Agent 检测或可选官方安装。
-7. 如果配置模型服务，用户选择 PPIO、Novita 或 Custom。
-8. 用户填写 API Key；没有 Key 时可打开对应官网注册或获取 Key。
-9. 页面用当前 base URL + API Key 请求 `GET <base-url>/v1/models`。
-10. 模型列表成功时默认选择第一个模型 ID；失败时允许手动输入，默认值为 `gpt-4.1`。
-11. 确认页展示 Agent 列表、Provider、base URL、模型 ID、写入路径和备份策略。
-12. GUI 按 Agent 循环调用 CLI 安装内核。
-13. 完成页展示每个 Agent 的结果和下一步命令。
-
-## 当前实现
-
-### GUI
-
-- `scripts/gui.py` 使用 Python 标准库 HTTP server。
-- 页面是内嵌 HTML/CSS/JS，不引入 React、Vite、Electron 或 Tauri。
-- API 包括：
-  - `GET /api/status`
-  - `POST /api/probe`
-  - `POST /api/models`
-  - `POST /api/install`
-  - `POST /api/open-register`
-- 多选 Agent 时，Python 层循环调用 `scripts/install.sh`，CLI 仍保持单 Agent。
-- `AGENT_CATALOG` 是 GUI 和 API 共用的 Agent 元数据源。
-- Guide-only Agent 不调用安装内核，只返回官方安装/配置指引。
-
-### CLI
-
-- `scripts/install.sh` 支持 `--agent codex|claude-code|opencode|kilo-cli|aider`。
-- Provider 支持 `ppio|novita|custom`。
-- `--install-agent` 才会调用 allowlist 内包管理器安装源。
-- `--check-agent-only` 只检测或安装 Agent，不写模型配置。
-- 写配置前会备份旧文件。
-
-### Agent 分类
-
-可一键配置：
-
-- Codex
-- Claude Code
-- OpenCode
-- Kilo CLI
-- Aider
-
-只做引导：
-
-- OpenClaw、Hermes
-- Cursor、Kiro、Gemini CLI
-- Cline、Continue、Qwen Code、Kilo VS Code
-
-### Provider 默认值
-
-PPIO：
-
-- 官网：`https://ppio.com/`
-- Base URL：`https://api.ppio.com/openai`
-- Chat 请求：`https://api.ppio.com/openai/v1/chat/completions`
-
-Novita：
-
-- 官网：`https://novita.ai/`
-- Base URL：`https://api.novita.ai/openai`
-- Chat 请求：`https://api.novita.ai/openai/v1/chat/completions`
-
-## 配置写入策略
-
-### Codex
-
-写入：
-
-- `~/.codex/config.toml`
-- `~/.oneagent/env`
-
-完成后提示：
-
-```bash
-source ~/.oneagent/env && codex
-```
-
-### Claude Code
-
-写入：
-
-- `~/.claude/settings.json`
-
-字段：
-
-- `ANTHROPIC_BASE_URL`
-- `ANTHROPIC_AUTH_TOKEN`
-- `ANTHROPIC_MODEL`
-
-完成后提示：
-
-```bash
-claude
-```
-
-### OpenCode / Kilo CLI
-
-写入：
-
-- `~/.config/opencode/opencode.jsonc`
-- `~/.config/kilo/kilo.jsonc`
-- `~/.oneagent/env`
-
-配置使用 `@ai-sdk/openai-compatible`，Base URL 写成 `<api-base-url>/v1`。
-
-### Aider
-
-写入：
-
-- `~/.oneagent/aider.env`
-
-完成后提示：
-
-```bash
-source ~/.oneagent/aider.env && aider --model openai/<model>
-```
-
-## 验收标准
-
-- [ ] 首屏展示 Agent 分组目录和安装状态。
-- [ ] 可以跨分类多选 Agent。
-- [ ] 可一键配置 Agent 能写入本地配置。
-- [ ] Guide-only Agent 不写本地配置，只返回指引。
-- [ ] 可以跳过模型服务配置，并且不要求 API Key。
-- [ ] 跳过配置时不写 `~/.oneagent/env`。
-- [ ] PPIO 和 Novita 显示正确官网和 base URL。
-- [ ] Custom 允许填写自定义 base URL。
-- [ ] 可以通过 `GET <base-url>/v1/models` 获取模型 ID。
-- [ ] 模型列表失败时可以手动输入模型 ID。
-- [ ] API Key 不出现在 GUI 日志或子进程命令行参数中。
-- [ ] CLI 仍可独立运行。
-- [ ] README 不推荐日常使用明文 `--api-key` 参数。
-
-## 验证方式
-
-自动测试：
-
-```bash
-./tests/install_test.sh
-python3 tests/gui_smoke_test.py
-bash -n scripts/install.sh tests/install_test.sh
-python3 -m py_compile scripts/gui.py tests/gui_smoke_test.py
-```
-
-手动验收：
-
-1. 运行 `python3 scripts/gui.py`。
-2. 选择 Codex + OpenCode + OpenClaw。
-3. 选择跳过配置，确认可以直接进入最终确认页。
-4. 选择 PPIO 或 Novita，确认无 Key 时能打开官网。
-5. 使用 mock key 测试连接，确认 401/403 被解释为端点可达但 Key 被拒绝。
-6. 模型列表失败时，确认仍可手动输入模型 ID 并继续。
-
-## 暂不做
-
-- Windows 原生安装器。
-- Electron / Tauri 桌面包。
-- 重新分发 Agent 包体。
-- 为每个 Agent 单独配置不同 Provider 或模型。
-- 企业 SSO。
-- 团队管理和账单。
-- Agent 自动更新。
-- 复杂模型路由界面。
-
-## 后续方向
-
-1. 将注册页参数和官网归因数据打通。
-2. 增加更完整的本地诊断报告。
-3. 支持设备码登录，减少手动粘贴 Key。
-4. 在有稳定激活数据后，再考虑桌面安装包。
-5. 多个 Agent 跑通后，再考虑 Agent Hub。
+历史方案中的 localhost HTTP、Cookie/Origin、解释器启动器和旧 GUI 文件均已删除。保留本文件只是为了说明早期产品边界；新增功能不得依赖其中的路径、端口或命令。
diff --git a/docs/per-agent-config-plan.md b/docs/per-agent-config-plan.md
index ab666db8..777cd64b 100644
--- a/docs/per-agent-config-plan.md
+++ b/docs/per-agent-config-plan.md
@@ -1,106 +1,28 @@
-# 选择页排序修复，与详情页分化的评估
+# Per-Agent 配置计划（已实施）
 
-起因是两个诉求：激活环境页没把重要 Agent 排在前面；每个 Agent 的配置界面完全一致。参考对象是 CC Switch。
+> 当前实现位于 `internal/config` 和 `internal/app`。本文保留设计结论，旧脚本路径不再适用。
 
-结论先行：**只做选择页排序修复。** 详情页按适配器分化经核对后不成立——它要暴露的多数是内部实现差异，而隐藏这些差异正是 OneAgent 的价值。唯一值得单独评估的是 Claude Code 的快速小模型字段。
+## 适配器
 
-调研版本 `cc-switch` 3.18.0（commit `708b387`），MIT，克隆在被忽略的 `output/reference/cc-switch`。背景见 [CC Switch 参考笔记](cc-switch-reference-notes.md)。
+| Agent | 配置适配器 | 凭据交付 |
+| --- | --- | --- |
+| Codex | TOML provider + 专属 env | `oneagent_env` |
+| Claude Code | settings JSON + native env | `native_env` |
+| OpenCode/Kilo CLI | OpenAI-compatible JSON + 专属 env | `oneagent_env` |
+| Aider | env 脚本 | `config_file` |
 
-## 1. CC Switch 的表单结构
+适配器由 `agents.lock.json.config_adapter` 选择；新增 Agent 不复制版本、命令或路径常量。配置写入会保留用户未管理字段、创建安全备份并原子替换。
 
-它的形态是三层，不是「每个 Agent 一套独立表单」：
+## Claude Code fast model
 
-```
-共享 ProviderForm 编排器（2693 行）
-  + 共享字段组件与 hooks
-      hooks/    24 个文件 4733 行（useOpencodeFormState、useHermesFormState、useCodexConfigState…）
-      shared/   5 个文件 410 行（ModelInputWithFetch、EndpointField、ApiKeySection、ModelDropdown）
-      helpers/  166 行
-      BasicFormFields 177 · ApiKeyInput 69 · ProviderAdvancedConfig 182
-  + 各应用专属 FormFields 区块
-      OpenCode 1148 · Codex 1107 · Claude 1127 · OpenClaw 673 · Hermes 569 · Gemini 213
-```
-
-共享层本身接近 6000 行，专属区块坐在它上面。这与「共用骨架 + 按需分区块」是同一种形态。
-
-几点需要说准：
-
-- **`OmoFormFields`（1321 行）不是同级 Agent。** `types.ts:8-9` 写的是 `"omo" // Oh My OpenCode` 与 `"omo-slim"`，属 OpenCode 下的配置类别。
-- **Gemini 表单不只有 OAuth。** 官方 Google 路径走 OAuth，自定义或第三方 Gemini Provider 仍可填 Key、Endpoint、模型并拉取模型列表。213 行是因为它复用共享字段，不是因为没什么可填。
-- **Codex 的上游格式三选不是 `wire_api` 三选。** 源码明确标注 Codex 的 `wire_api` 固定为 `responses`；三选属于它的代理转换层——而本地代理在 [产品边界基线](product-boundary-baseline.md) 里是明确禁止范围。
-- **它并非「用户必须自己懂原始格式」。** `settingsConfig` 是原生 JSON 对象存储，但 UI 与 Service 层仍会理解、校验和编辑字段语义。参考笔记第 2 节的表述过头了。
-
-**正确的借鉴原则**：只有当用户面对一个真实的、可选择的语义需求时才分化 UI。**底层配置文件不同本身不构成分化理由。**
-
-## 2. 我们的适配器差异，哪些是用户的选择
-
-`_write_agent_config`（`oneagent/installer.py:399`）分派四个适配器，写的东西确实不同：
-
-| Agent | 目标 | 密钥去处 | 模型 |
-| --- | --- | --- | --- |
-| Codex | `config.toml` 的 `[model_providers.oneagent]` | env 文件，经 `env_key` 间接引用 | `model` 单值 |
-| Claude Code | `settings.json` 的 `env` | 写进配置文件（`ANTHROPIC_AUTH_TOKEN`） | `ANTHROPIC_MODEL` + `ANTHROPIC_SMALL_FAST_MODEL` |
-| OpenCode / Kilo | `provider.oneagent` + `models` 映射 | env 文件，`{env:...}` 占位 | `oneagent/<model>` |
-| Aider | shell / PowerShell 脚本 | 写进脚本（`secret=True`） | 不写，靠启动参数 |
-
-按第 1 节的原则筛一遍，**只有一项是用户的选择**：
-
-- **Claude Code 的 `ANTHROPIC_SMALL_FAST_MODEL`**（`installer.py:384-385`）现在被强制等于主模型。「主模型 + 快速小模型分别指定」是一个真实能力，用户可能确实想让小模型更便宜。这是唯一值得建 UI 的差异。
-
-其余三项都只是内部实现，不该出现在界面上：
-
-- 密钥最终写到配置文件还是 env 文件；
-- 模型放在配置文件还是启动参数；
-- 用哪种 env 占位格式（`env_key` / `{env:...}` / `export`）。
-
-用户对这些没有选择权，讲出来只是增加认知负担。**隐藏它们正是产品价值。**
-
-## 3. 先前判断中已修正的错误
-
-记下来避免重复踩：
+`small_fast_model` 是可选字段。为空时回退主模型；有值时同时写入 settings 和 native env。前端 Advanced section、Go binding 和 CLI 使用同一字段。
 
-- **「Aider 留空会使启动命令缺模型参数」错。** `install_many` 与 `activate_agent` 都在写任何东西之前无条件补齐模型（discovery，失败则 `fallback_probe_model`）。后端拿到的 `model` 永远非空，「留空则由端点自动选择」对 Aider 同样成立。误推的环节是漏掉了 resolve 这一步。
-- **「只有 Codex/OpenCode/Kilo 需要 source」错。** `_next_step` 里 Aider 也要 `source ~/.oneagent/aider.env && aider --model openai/<model>`。**只有 Claude Code 是裸 `claude`。**
-- **「详情页对所有 Agent 给出相同启动说明」错。** 输入表单是共用的，但 `restart` 与 `next` 由后端按 Agent 生成，详情页直接显示 `applied.restart` / `applied.next`，结果区本就是分化的。
-- **「rank 完全没用上」错。** `catalog.py` 已按 rank 排序输出，选择页拿到的就是排好的数组。准确的说法是 rank 没有参与「首屏还是折叠」的决定。
-- **「guide-only 必须不可勾选」错，且会破坏现有流程。** `installer.py:1079-1082` 对 `config_mode == "guide"` 返回 `status: "guide-only"`，把 `meta["guide"]` 放入 `next_steps`，不装包、不写私有配置；Review 页显示「显示引导」。**合规要求是「不自动配置」，不是「不允许选择」。**
+## 验收
 
-## 4. 要做的：选择页排序修复
-
-`AgentSelectionPage.tsx:13` 以 `group === "auto"` 决定首屏，`:14-20` 把其余按 `group.id` 塞进「更多分类」折叠。结果 Kilo（rank 8）、Aider（9）在首屏，而 Cursor（3）、OpenClaw（5）、Hermes（6）被折叠。总览页 `EnvironmentOverviewPage.tsx:35-37` 已按 rank 排并以 `PRIMARY_RANK_LIMIT = 6` 划线，选择页没跟上。
-
-改动：
-
-- 把 rank 排序与首屏阈值抽到 `frontend/src/state/ranking.ts`，选择页与总览页共用，避免第三次各写一遍。
-- 选择页改用统一排序划分首屏与折叠区，删掉 `automatic` / `additionalGroups` 两个 `useMemo`。
-- 首屏标题从「可一键配置」改为「常用 Agent」——按 rank 混排后首屏含 guide-only，原标题不再成立。折叠区标题改为「更多 Agent」。
-- **guide-only 保持可勾选**。`AgentRow` 的 `disabled` 条件不动（仍只在 `platforms.length === 0` 时禁用）。注意「仅引导」徽标只在该 Agent **未安装** 时出现——`AgentRow` 的状态优先显示「已安装」。本机已装 Cursor 时首屏三个 guide-only 行都显示「已安装」，说明这一点的是行内那句「显示官方安装与配置步骤」，断言应该盯它而不是徽标。
-
-测试：
-
-- `AgentSelectionPage.test.tsx`（新建）——断言渲染顺序为 rank 顺序、Cursor 在 Kilo 之前；断言 guide-only 行的 checkbox 未禁用；mock 的 catalog 故意逆序传入，确保页面不依赖服务端顺序。
-- `ranking.test.ts`（新建）——排序、并列按 id、`undefined` 视作空、阈值取等号侧。
-- `wizard.spec.ts` 已有 rank 齐全的 mock（`:15-20`），补首屏顺序与 guide-only 可勾选断言。
-
-改完开 `8765` 用真实 DOM 复查顺序与勾选态。
-
-## 5. 暂缓：按 `configAdapter` 拆详情页
-
-按第 2 节的筛选结果，Codex / OpenCode / Kilo / Aider 的「专属区块」内容都是内部实现说明，不建。不启动 `configAdapter → 多区块` 体系，也不为此改 `AgentCatalogItem` 契约。
-
-## 6. Claude Code 双模型字段 — 已实现（产品已确认）
-
-落实情况：产品确认支持后按本节落点实施。`write_claude_config` 与 `write_agent_env`、`activate_agent` 增可选 `small_fast_model`（留空回退主模型），activate 端点与 `frontend/src/types/api.ts` 同步；`AgentDetailPage` 的 `AdvancedSection` 内增 Claude Code 专属「快速小模型」字段并经 `api.activateAgent` 传 `small_fast_model`。`installer.py` 两侧用例（给值 / 留空）守住 100% 分支门禁，`AgentDetailPage.test.tsx` 与 `client.test.ts` 覆盖前端两侧。未建立完整分区块体系——仅这一个字段。
-
-若产品确认支持「主模型 + 快速小模型」，落点是现有 `AdvancedSection` 里增一个 Claude Code 专属可选字段，留空回退到主模型。涉及 `write_claude_config` 与 `activate_agent` 增一个可选参数、activate 端点与 `types/api.ts` 同步，以及 `installer.py` 100% 分支门禁要求的两侧用例（给值 / 留空）。
-
-**仅这一个字段不需要建立完整的分区块体系。** 先确认产品是否要这个能力，再决定是否实施。
-
-## 7. 明确不做
-
-- CC Switch 的上游格式三选、prompt cache 路由、reasoning 档位、四项分价、任意 headers 与 extra options —— 我们的适配器不写这些，建了 UI 就是空承诺；其中上游格式三选依赖它的代理转换层，属产品边界禁止范围。
-- 每 Agent 独立表单组件 —— 我们四个适配器的共用部分远大于差异部分。
-- guide-only Agent 的配置界面 —— 两个页面上都只提供官方引导入口。
-- 改 `rank` 数值 —— 当前排序是上一轮的决定。
+```bash
+go test ./internal/config ./internal/app
+bash tests/install_test.sh
+go run ./cmd/oneagent-rc adopted
+```
 
-相关文档：[CC Switch 参考笔记](cc-switch-reference-notes.md)、[产品边界基线](product-boundary-baseline.md)、[前端管理控制台改造计划](frontend-management-console-plan.md)。
+配置采用检查使用丢弃端口和假 Key，确保 Agent 读取了配置后才会在网络层失败；它不需要真实 Provider Key。
diff --git a/docs/provider-rc-testing.md b/docs/provider-rc-testing.md
index e7485ae0..7219cc8f 100644
--- a/docs/provider-rc-testing.md
+++ b/docs/provider-rc-testing.md
@@ -4,7 +4,7 @@
 
 OneAgent 将 Provider 测试分为两个层级：
 
-1. 本地临时预检：验证测试脚本、鉴权头和三类协议请求结构可以工作。
+1. 本地预检：复用 Go Provider 客户端，验证鉴权头和三类协议请求结构。
 2. 正式 Release Candidate：使用 PPIO、Novita 各自的受保护低权限 Key 验证真实供应商能力。
 
 本地预检不能替代正式 RC，也不能用于宣称 PPIO 或 Novita 已通过兼容性验收。
@@ -14,6 +14,7 @@ OneAgent 将 Provider 测试分为两个层级：
 每个正式 Provider 必须分别提供以下变量，即使三个变量暂时使用同一个模型 ID，也不得合并为单一变量：
 
 ```text
+ONEAGENT_<PROVIDER>_API_KEY
 ONEAGENT_<PROVIDER>_OPENAI_MODEL
 ONEAGENT_<PROVIDER>_ANTHROPIC_MODEL
 ONEAGENT_<PROVIDER>_RESPONSES_MODEL
@@ -22,51 +23,33 @@ ONEAGENT_<PROVIDER>_RESPONSES_MODEL
 对应请求为：
 
 | 槽位 | 请求 |
-|---|---|
+| --- | --- |
 | OpenAI | `POST /v1/chat/completions` |
 | Anthropic | `POST /v1/messages`，包含 `X-Api-Key` 和 `Anthropic-Version` |
 | Responses | `POST /v1/responses` |
 
 `GET /v1/models` 只验证鉴权和模型目录可访问，不能证明三个推理协议均兼容。
 
-## 临时 apiproxy 档案
+## 本地执行
 
-截至 2026 年 7 月 22 日，本地低 Token 请求确认 `openai/gpt-5.6-terra` 在以下四个请求上均返回 HTTP 200：
-
-```text
-GET  https://apiproxy.paigod.work/v1/models
-POST https://apiproxy.paigod.work/v1/chat/completions
-POST https://apiproxy.paigod.work/v1/responses
-POST https://apiproxy.paigod.work/v1/messages
-```
-
-临时档案的三个模型槽位当前都设置为：
-
-```text
-openai/gpt-5.6-terra
+```bash
+go run ./cmd/oneagent-provider-smoke --provider ppio --timeout 30s
 ```
 
-`openai/gpt-5.6-luna` 只支持两类协议，因此不能作为三协议预检的统一默认模型。
-
-本地执行命令：
+命令只从环境变量读取 Key 和模型，不接受命令行凭据，也不会把响应正文写入日志。正式 RC：
 
 ```bash
-python3 scripts/provider_rc_smoke.py \
-  --provider apiproxy \
-  --api-key-json ~/.codex/auth.json \
-  --api-key-field OPENAI_API_KEY \
-  --timeout 45
+go run ./cmd/oneagent-provider-smoke --provider all --timeout 30s
 ```
 
-Key 从 JSON 文件内部读取，不作为命令行参数值传递。当前本机认证文件中的实际字段名是 `OPENAI_API_KEY`，不是 `OPENAIKEY`。
+`all` 严格只运行 PPIO 和 Novita。自定义端点应在单独的环境隔离中运行，临时代理结果不能替代正式供应商证据。
 
 ## 正式 RC 门禁
 
-`.github/workflows/release-candidate.yml` 的 `--provider all` 只运行 `ppio` 和 `novita`。正式 RC 仍要求：
+`.github/workflows/release-candidate.yml` 的 Go smoke 仍要求：
 
 - `ONEAGENT_PPIO_API_KEY` 和 `ONEAGENT_NOVITA_API_KEY` 存放在受保护 CI Secret。
 - 两个 Provider 分别配置 OpenAI、Anthropic、Responses 三个模型变量。
-- 四个端点全部成功，并继续执行真实 Agent 首次请求验收。
-- 任一协议不支持时，明确降级对应 Agent/Provider 组合，不使用代理预检结果绕过发布门禁。
-
-临时 `apiproxy` 档案不进入 `--provider all`，也不写入正式 RC workflow 的 Secret 或变量列表。
+- `/v1/models`、Chat Completions、Responses 和 Anthropic Messages 全部成功。
+- 随后的真实 Agent 安装、PATH、锁定版本和无密钥配置采用检查全部通过。
+- 任一协议不支持时，明确阻止对应 Agent/Provider 组合，不使用其他协议或临时端点绕过门禁。
diff --git a/docs/public-site-operations.md b/docs/public-site-operations.md
index 3250d5e6..c21a8564 100644
--- a/docs/public-site-operations.md
+++ b/docs/public-site-operations.md
@@ -1,36 +1,25 @@
-# OneAgent 公开分发站运营与发布手册
+# OneAgent 公开站运营与发布手册
 
-状态：实施中，适用于 `technical-preview-unsigned` 和未来逐平台 Stable 发布。
+状态：已实施。
 
-## 1. 固定架构
+## 架构边界
 
-- `frontend/` 是随 Launcher 打包的本地七页向导，继续服从无 CDN、资源内联和本地 API 安全约束。
-- `site/` 是独立的 Astro 静态站，只提供产品说明、下载、教程、兼容目录、安全政策、支持和企业服务页面。
-- 两者不共享路由、状态或运行时组件；首期只复用品牌语言、真实截图和 Agent 标识资产。
-- 官网不进入 OneAgent 安装包，网站构建失败不能改变 Launcher 的本地运行行为。
+- `frontend/` 是随桌面 App 打包的 React 客户端。
+- `site/` 是独立构建和部署的 Astro 静态站，不进入 App 包体。
+- `.github/workflows/technical-preview.yml` 只构建 Go/Wails App 资产并创建 Draft GitHub Release。
+- `.github/workflows/site.yml` 只测试、构建和部署 GitHub Pages。
 
-## 2. 唯一发行事实源
+两个工作流没有 artifact 或 job 依赖。发布者人工审核并发布 Draft Release 后，`release.published` 事件会触发站点重建。
 
-公开下载数据由三层组成：
+## 版本事实源
 
-1. `release/release-manifest-<platform>-<arch>.json`：构建产生的版本、平台、架构、Agent 锁定版本和 artifact 哈希。
-2. `release/SHA256SUMS-<platform>-<arch>.txt`：artifact 与 manifest 的独立校验记录。
-3. `distribution/channels.json`：人工审核的平台公开状态、原生构建/cleanroom 证据和下载渠道。
+公开站在构建时调用 GitHub Releases API，只读取已发布、非 Draft 的 Release。页面上的版本标签、发布日期、下载地址、文件大小和可用的 SHA-256 digest 均来自该 API；没有 Release 时页面明确显示尚未发布。
 
-`scripts/build_release_index.py` 校验三层一致性并生成 `site/src/generated/release-index.json`。可公开下载的平台必须同时满足：
+站点不读取 App 的本地 `release/` 目录，不复制下载资产，也不维护版本回退值。Agent 目录直接读取 `agents.lock.json`，Provider 目录直接读取根目录的 `providers.lock.json`；运行时端点和公开披露字段由同一份清单管理。
 
-- manifest 和 checksum 文件存在；
-- artifact 文件大小与 SHA-256 完全一致；
-- `native_build=true`；
-- `cleanroom=verified` 且 evidence 非空；
-- 有且只有一个 primary 官方下载渠道；
-- 外部镜像使用 HTTPS，并声明与 artifact 完全相同的 `verified_sha256`；
-- available 渠道有明确的 `published_at`；
-- 渠道与签名状态一致，unsigned 构建不能进入 Stable。
+私有仓库构建需要提供具有 `contents:read` 权限的 `GITHUB_TOKEN`。独立 Pages 工作流使用当前任务的 GitHub token；未提供 token 的本地构建若无法读取私有仓库，会渲染“尚无已发布版本”。
 
-网站的 `/release-index.json` 与下载页读取同一份生成数据，禁止再维护手工版本表。
-
-## 3. 本地开发和验收
+## 本地验证
 
 ```bash
 cd site
@@ -41,83 +30,29 @@ npx playwright install chromium
 npm run test:e2e
 ```
 
-`npm run prepare:data` 会从仓库根目录的 manifest、渠道配置、`agents.lock.json` 和 Provider 公开配置重新生成网站数据，并把当前标记为 available 的官方同包 artifact 复制到网站构建目录。
-
-`site/src/generated/` 与 `site/public/downloads/` 都是可再生目录，**均不提交到 Git**：`catalog.json` 是 `agents.lock.json` 加 Provider 配置的纯函数，提交它只会让每次构建产生 diff；`release-index.json` 含 artifact 校验和，提交等于把某一台机器的构建结果冻进仓库。干净检出下 `npm run build` 会先跑 `prepare:data` 重新生成，无需额外步骤。
-
 模拟 GitHub Pages 子路径部署：
 
 ```bash
 SITE_URL=https://example.com BASE_PATH=/OneAgent npm run build
 ```
 
-**这份产物不能用 `astro preview` 在本地查看。** `BaseLayout.astro` 会输出绝对 URL 的 `<base href>`，而同一份 CSP 声明了 `base-uri 'self'`：从本机 origin 伺服时浏览器拒绝该 base 标签，样式表与 Agent 标识全部 404，**而每个页面仍然返回 200，只是退化成无样式 HTML**。部署到 Pages 时 base 与页面同源，`'self'` 放行，因此线上不受影响。
-
-跑完这条命令后要恢复可预览的产物，直接重新 `npm run build` 即可。`site.spec.ts` 有一条断言同时检查无 4xx、背景色取自本站样式表、图片全部解码成功，正是为了让这种「200 但坏了」的状态在测试里可见而不是靠肉眼发现。
-
-## 4. 受控预览发布
+该子路径产物的绝对 `<base href>` 只适用于配置的 origin。恢复本地预览时重新运行普通 `npm run build`。
 
-`.github/workflows/technical-preview.yml` 的顺序固定为：
+## 发布顺序
 
-1. 四个平台原生构建 unsigned preview；
-2. 打包 CLI 冒烟和包体检查；
-3. macOS arm64 执行真实 cleanroom；
-4. 汇总所有平台 manifest 与 checksum；
-5. 生成公开 release index、执行网站单元/类型/完整性、三档视口浏览器与可访问性检查；
-6. 只把 `distribution/channels.json` 中标记为 available 的平台 artifact、manifest、checksum 和 release index 放进 Draft GitHub prerelease；
-7. 人工核对并在 GitHub 上公开该 prerelease；
-8. 再次手动运行工作流，关闭 `create_draft_release`、开启 `deploy_pages`；工作流会丢弃本次重建的包体，重新下载已公开 prerelease 的不可变资产来生成下载页，通过门禁后部署 GitHub Pages。
-
-手动触发需要指定 preview tag。`deploy_pages` 默认关闭；Tag 触发只创建不可变 Draft，不会自动部署网站。Draft 只在人工复核平台状态、发行说明和下载校验后公开。工作流拒绝覆盖同一 tag 下已有的不同字节；任何包体变化都必须先提升 OneAgent 版本并使用新 tag，不得在同一版本下替换 artifact。
-
-四个平台的构建结果仍会作为 CI artifact 保留用于验证，但未标记 available 的 Windows、Linux 或 macOS x64 包不会进入 GitHub Release，也不会被复制到网站下载目录。
+1. 运行 `Technical Preview Packages`，构建并验证各平台 App 资产。
+2. 工作流以新 tag 创建不可变 Draft prerelease；已有 tag 会直接失败，不覆盖资产。
+3. 人工检查资产、校验和、签名状态和发行说明后发布 Release。
+4. `Public Site` 工作流自动从默认分支构建站点，从该 Release 读取版本与下载信息并部署 Pages。
+5. 仅修改站点、Agent 目录或 Provider 披露时，合入 `main` 即可独立部署，不触发 App 构建。
 
 GitHub repository variables：
 
-- `ONEAGENT_PUBLIC_SUPPORT_URL`：公开 Issues、Discussions 或其他可访问的反馈入口；为空时网站明确显示尚未启用。
-- `ONEAGENT_PUBLIC_BUSINESS_EMAIL`：公开商务邮箱；为空时企业页不展示虚构联系方式。
-
-域名、DNS、备案、Pages 开关和签名证书属于仓库外部依赖。
-
-## 5. 镜像与撤回
-
-新增官网外镜像时：
-
-1. 上传现有官方 artifact，禁止重新压缩、追加文件和二次签名；
-2. 下载镜像文件并重新计算 SHA-256；
-3. 在 `distribution/channels.json` 中使用 `kind=mirror` 并填写与 manifest 完全相同的 `verified_sha256`；
-4. 在镜像的 `audit` 对象中记录 `uploaded_by`、`uploaded_at`、`verified_at`、`withdrawal_owner` 和 `withdrawn`；撤回时补充 `withdrawn_at`。镜像必须使用 HTTPS，且不能成为 primary 官方渠道；
-5. 重新构建网站，生成器会拒绝哈希未确认的外部镜像。
-
-发生错误或安全事件时，将目标状态改为 `withdrawn`、移除下载链接并重建网站，同时撤回所有渠道。禁止在同一个版本号下替换为不同字节的文件；修复后必须发布新版本。
-
-## 6. Provider 合作披露
-
-Provider 的公开商业数据保存在 `distribution/providers.json`，与 Agent rank 和运行时兼容逻辑分离。
-
-- `relationship=none`：只链接官方主页。
-- `relationship=referral` 或 `sponsor`：必须同时填写 disclosure 和 referral URL。
-- 商业关系不能改变 Agent/Provider 技术结论、默认选择、连接探测或页面排序。
-- OneAgent 不代理推理请求、不托管 Key、不代收充值，不承诺 Provider 的永久价格或固定免费额度。
-- 首期只链接官方价格页，不在仓库内复制容易过期的价格表。
-
-## 7. 支持、统计与增长
-
-- 文档、校验信息与已知限制保持公开，社群不是下载前置条件。
-- 应用继续默认无遥测；网站当前也不加载客户端分析脚本。
-- 如后续启用无 Cookie 聚合统计，允许事件仅限页面访问、下载点击、快速开始入口和企业联系入口；禁止设备指纹、跨站身份、API Key、本地路径和模型请求内容。
-- 初始漏斗目标：主页到下载页 20%，下载用户进入快速开始 40%，每 100 次下载的重复性安装支持请求少于 20。
-
-## 8. 企业服务与产品化门禁
-
-首期只销售三个可复用结果：团队启用、环境标准化和商业支持。内部镜像仍只能分发 OneAgent 官方同包产物，不得包含未授权 Agent 二进制。
+- `ONEAGENT_PUBLIC_SUPPORT_URL`：公开支持入口；为空时不展示虚构地址。
+- `ONEAGENT_PUBLIC_BUSINESS_EMAIL`：公开商务邮箱；为空时不展示虚构邮箱。
 
-在至少获得 3 个设计合作方、其中 2 个付费试点前，不开发专业版许可证系统。若试点反复提出团队模板、合规报告、组织版本策略或内部升级策略，必须新建 ADR，重新评估权限、秘密管理、迁移与隐私边界。
+## Provider 与稳定版边界
 
-## 9. Stable 门禁
+Provider 商业数据保存在 `providers.lock.json`，不能影响 Agent rank、兼容性结论、默认选择或连接测试。
 
-- macOS：Developer ID、notarization、stapled ticket、原生 cleanroom。
-- Windows：有效 Authenticode、原生构建、SmartScreen 场景验证。
-- Linux：按实际架构原生构建和 cleanroom。
-- 每个平台独立进入 Stable；网站允许同一时间存在不同成熟度。
-- Stable 初期仍采用手动升级说明，不在本阶段加入自动更新。
+Stable 仍需按平台满足签名、公证和原生 cleanroom 门禁。GitHub Release 是公开版本与资产的事实源，不替代 App 发布流程中的产物验证。
diff --git a/docs/recent-work-summary.md b/docs/recent-work-summary.md
index 57172b62..84a752a3 100644
--- a/docs/recent-work-summary.md
+++ b/docs/recent-work-summary.md
@@ -1,88 +1,32 @@
-# 近期工作纪要
+# Recent Work Summary
 
-分支 `codex/trusted-distribution-site`，12 个提交，97 文件 +13650/−110。已推送 `origin` 与 `maimory`。
+> 更新：2026-07-31。本文记录当前可复核的 Go/Wails 收尾结果；旧的 Python 计数和命令不再是验收依据。
 
-四条线：公开分发站、安装链路可验证、配置链路能用、入口分流。每条都是先实测、再修、再用测试固定住结论。
+## 已完成
 
-发现的三个缺陷有个共同点：**它们都表现为成功**——页面返回 200 但整站无样式，Agent 报 `configured` 但启动即失败，`tsc` 干净但返回用户被送去营销页。所以每条都补了能看见「假成功」的断言，而不只是修掉现象。
+- Go backend 覆盖 catalog、Provider、安装、配置发现/写入、profile、secret、备份、权限和 CLI。
+- React 已切换到生成的 Wails bindings；桌面生产路径不使用 HTTP API。
+- 配置写入使用 Go golden fixtures，直接锁定 JSON/TOML 输出，不启动第二套 runtime。
+- `cmd/oneagent-release` 生成原生 Wails/Go 包、源码 ZIP、manifest、SHA-256 和第三方 notices。
+- `cmd/oneagent-rc` 覆盖隔离 npm prefix、真实锁定版本、PATH 解析和无密钥配置采用。
+- `cmd/oneagent-provider-smoke` 覆盖 models、Chat Completions、Responses、Anthropic Messages。
+- Docker/macOS cleanroom、Go race、React/site 构建和 Wails binding diff 均有独立入口。
 
-## 1. 公开分发站（`bc01bcd` → `67b3706`）
+## 当前验证入口
 
-独立的 Astro 静态站，26 页，无第三方脚本，CSP `default-src 'self'`。
-
-**核心决定是下载页的每个断言都必须可核对。** 版本、SHA-256、cleanroom 结论都由 `scripts/build_release_index.py` 从 `release/` 的实际产物生成，缺产物或校验和不符就拒绝出条目。手工维护版本表会让页面宣传一个从未构建出来的包，对未签名预览版而言这是最不能犯的错。
-
-`site/src/generated/` 与 `site/public/downloads/` 不入库：前者是 `agents.lock.json` 加 Provider 配置的纯函数，提交只会让每次构建产生 diff；后者含 artifact 校验和，提交等于把某台机器的构建结果冻进仓库。
-
-**过程中发现一个真实缺陷。** 站点在本地打开时整站无样式、图标全 404，但**每个页面仍返回 200**。根因是 `BaseLayout.astro` 输出绝对 URL 的 `<base href>`，与同文件 CSP 的 `base-uri 'self'` 冲突——浏览器拒绝该标签，资源路径全部落空。线上不受影响（Pages 与页面同源），但任何人手动带 `BASE_PATH` 构建后本地预览就是坏的，而症状是 200 而非报错。`site.spec.ts` 现在同时检查无 4xx、背景色取自本站样式表、图片全部解码，让这种「200 但坏了」的状态在测试里可见。这条断言做过反向验证：故意用 `/OneAgent` base 构建后，它确实失败。
-
-顺带修掉一个分发问题：源码归档白名单加 `site/src` 时把 `src/generated/` 一并扫进去了，发布的源码包会携带某台机器的校验和。原有测试只 grep 函数源码文本，看不到这个；新测试断言 `source_files()` 的实际返回值。
-
-## 2. 安装链路可验证（`7c30c5d`、`9a20b21`、`f271d88`）
-
-问题是「Agent 装得上」此前是个假设。手动实测确认装得上（两个锁定版本在 registry 上都存在，落到 PATH，版本相符），然后把结论固化成可重复的脚本。
-
-**`integrity` 记而不验。** `agents.lock.json` 为每个 npm 包记了 sha512，也有测试断言它存在，但 `install_locked_agent()` 全函数不读它——**版本锁住了，字节没有。** 现在安装前用 `npm view` 取 registry 声明的 `dist.integrity` 与清单比对。
-
-**这个校验正是镜像可被接受的前提。** 国内网络下官方 registry 常不可达，而 [产品边界基线](product-boundary-baseline.md) 第 5 节已把「授权镜像」列为优先级 2，条件是有许可证、版本锁定、校验值和上游地址。换 registry 是换取包的渠道，不是代理用户的网络——不建隧道、不转发流量，这是基线划的界。两个锁定包在 npmmirror 与官方源上的 integrity **逐字节相同**，所以这是同一份包的两个渠道。
-
-三个设计决定：默认永远官方源，镜像只能显式选择（自动切换会让用户不知道包从哪来）；只允许 HTTPS 且拒绝内嵌凭据（registry URL 会进入安装环境和日志）；实际使用的 registry 记入日志。镜像不得指向 OneAgent 运营的存储——重新分发商业 Agent 需要授权，而指向公开只读镜像不需要。
-
-验证分三层：`tests/test_install_contract.py`（42 用例，离线，断言 argv 而非执行）进常规 CI；`tests/real_install_test.sh` 真实安装，隔离 npm 前缀排在 PATH 最前，官方源与镜像双路径实测通过；`scripts/agent_e2e_smoke.py` 需真实 Key，手动运行。真实安装不进常规 CI——每次提交打 registry 既慢又会限流。
-
-**一处更正**：我曾判断「没有任何一层真的装包」，这是错的。`scripts/verify_locked_agents.py` 一直在真实安装，且覆盖全部五个 Agent。真实缺口是它之后的两步：shell 是否同意二进制可达，以及 Agent 带着配置能否真的应答。
-
-## 3. 配置链路能用（`74d6633`、`e3e4782`）
-
-装上不等于能用。把配置指向 `127.0.0.1:9`（丢弃端口）实测：Agent 报连接失败说明配置生效，报别的说明没生效。
-
-Codex 通——输出 `provider: oneagent`，证明它读了我们写的 `[model_providers.oneagent]`。
-
-**Claude Code 不通**——报 `Not logged in`。它不从 `settings.json` 取认证，而 OneAgent 报的是 `status: configured` 并告知运行 `claude`。用户照做会撞墙，且没有线索指向 OneAgent。
-
-根因是两处硬编码的集合：
-
-```python
-if agent_id in {"codex", "opencode", "kilo-cli"}:
-    write_agent_env(...)
+```bash
+go test ./...
+go test -race ./...
+bash tests/install_test.sh
+go run ./cmd/oneagent-release build --channel technical-preview-unsigned --source
+go run ./cmd/oneagent-release check release
 ```
 
-Codex 能用正是因为它多一个 env 文件，而**唯一无法认证的 Agent 恰好是被这个集合漏掉的那个**。
-
-修法是让 lock 声明凭据途径（`credential_delivery`：`oneagent_env` / `native_env` / `config_file`），Claude Code 另有 `env_vars` 声明它自己读的四个 `ANTHROPIC_*` 变量。`install_many`、`activate_agent`、`_next_step`、`_restart_hint` 都改为读声明，不再按 id 特判。实测确认按新的 `next` 指引启动后不再报 `Not logged in`。
-
-**缺陷能存在，是因为没有任何测试问过密钥怎么到达 Agent**，只验了文件写没写。现在 `CredentialDeliveryTests` 遍历所有 auto Agent 要求凭据可达，`test_release_policy` 要求 lock 声明安装器依赖的字段。
-
-## 前三条线交付时的状态
-
-Python 211 用例，`installer.py` 288/288 分支且零 partial，整体 96%；前端 68 用例 + 14 个 e2e；站点 10 + 33；真实安装 cleanroom 双 registry 通过。
-
-当时挂着三项待办：[配置链路审查](config-chain-audit.md) 的任务 2（消除剩余硬编码）与任务 3（无 Key 的配置可用性检查），以及 [按 Agent 分化配置界面](per-agent-config-plan.md) §6 的 Claude Code 双模型字段。**三项都已在下面两节完成**，最新数字见文末。
-
-## 4. 三项待办收尾（`3c8335c`）
-
-上文「未完成」的三项已全部完成：
-
-- **任务 2（lock 唯一真源）**：`backups` 遍历 lock 按 `config_path` 推导；`provider_config_base` 改收推理协议、移除 `providers.py` 两处 `"claude-code"` 比较；Windows 门禁改读 `windows_prerequisites`。`test_release_policy.py` 新增 `LockIsTheSourceOfTruthTests` 遍历 lock 守护。
-- **任务 3（无 Key 配置可用性检查）**：新增 `scripts/agent_config_adopted_check.py`。分类器 `classify_adoption` 离线进常规 CI（`test_rc_scripts.py` 用本轮两个真实输出覆盖）；实跑脚本无 Key、指向丢弃端口 `127.0.0.1:9`，已接入 `release-candidate.yml`。
-- **Claude Code 双模型字段（per-agent-config-plan §6）**：可选 `small_fast_model`（留空回退主模型）贯穿 `write_claude_config`/`write_agent_env`/`activate_agent`/activate 端点/`types/api.ts`；`AgentDetailPage` 高级选项加 Claude Code 专属「快速小模型」字段。
-
-## 5. 入口分流：着陆页只给未配置用户（`dfff727`）
-
-一个并发编辑引入了着陆页，`/` 无条件渲染它。这让**返回用户打开 OneAgent 落在营销页而不是自己的环境总览**，等于把 `LandingRoute` 专门防的行为又放回来了，8 个从 `/` 进入的 e2e 因此失败。补一个漏掉的 `useWizard` import 只能让 `tsc` 干净，不解决行为问题。
-
-修法是让根路径先读 status：已有 Agent 指向某处、或存在已激活档案，就跳 `/overview`；只有未配置的机器才看到着陆页。两处判断都要 status，所以 `WizardProvider` 上移到整个 router 之外；着陆页在 `AppWindow` 之外渲染——它是整页文档，不是应用窗口里的一个视图。
-
-原实现做不到这个判断：`pathname` 检查在 Provider 外面，读不到状态。恢复的 `LandingRoute` 保留了等待首次 status 读取的那一步，理由和当初一样——fetch 在 effect 里启动，首帧 `statusState` 是 `idle` 而非 `loading`，不等就会让返回用户闪一下着陆页。
-
-测试改法：`wizard.spec.ts` 五处入口改为 `/#/setup/agents`（它们测的是向导流程，不是路由决策），另补一条专测分流的用例，同时断言着陆页**不在** `.app-window` 内——把上面那个结构约束做成回归保护。`overview.spec.ts:264` 原样覆盖另一侧，两侧都有关卡。
-
-## 当前测试现状
+需要真实网络和受保护凭据的检查只在 Release Candidate workflow 执行。Aider 的 Python 3.12 是其上游安装流程的可选外部前置条件，不属于 OneAgent 构建或发行包。
 
-Python 222 用例，`installer.py` 298/298 分支且零 partial，整体 96%；前端 71 单测 + 15 个 e2e（新增着陆页分流一条），覆盖率语句 100% / 分支 97%；`tsc --noEmit` 与 `vite build` 通过。真机确认已配置的机器访问 `/` 直达环境总览。
+## 设计结论
 
-## 相关文档
-- [空白机器可用性验证计划](blank-machine-verification-plan.md) —— 三层验证的设计与实测结论
-- [配置链路审查](config-chain-audit.md) —— 实测方法、硬编码清单与三项任务的落实情况
-- [公开分发站运营与发布手册](public-site-operations.md)
-- [CC Switch 参考笔记](cc-switch-reference-notes.md)
+- `agents.lock.json` 是 Agent 元数据唯一真源；Go catalog 不复制版本和来源。
+- shell wrapper 只定位已构建的 CLI，不按需构建、不调用解释器。
+- source map、远程资源、secret、Agent 二进制和任何语言 runtime 都不能进入发行 ZIP。
+- Wails Alpha 阶段只发布 `technical-preview-unsigned`；Stable 签名/公证另行验收。
diff --git a/docs/release-evidence/0.2.0-dev-macos-arm64.md b/docs/release-evidence/0.2.0-dev-macos-arm64.md
index ba4a9030..568b55cc 100644
--- a/docs/release-evidence/0.2.0-dev-macos-arm64.md
+++ b/docs/release-evidence/0.2.0-dev-macos-arm64.md
@@ -1,9 +1,10 @@
-# OneAgent 0.2.0-dev macOS arm64 发行证据
+# OneAgent 0.2.0-dev macOS arm64 历史发行证据
+
+> 历史记录：该包来自迁移前的预览流程，不代表当前发行实现。当前包由 `cmd/oneagent-release` 生成；本文件仅保留旧 SHA-256 以便审计。
 
 状态：`technical-preview-unsigned`，不是 Stable。
 
 - 构建平台：macOS arm64
-- Python：3.12.13
 - 产物：`OneAgent-0.2.0-dev-technical-preview-unsigned-macos-arm64.zip`
 - SHA-256：`dad3f145b8710caf45c7de1cc8e8dd6fdfbdb00f6b6dc5cedf06dc49348cd46e`
 - Manifest 构建时间：2026-07-26T10:14:28.949648Z
diff --git a/docs/wails-v3-migration-plan.md b/docs/wails-v3-migration-plan.md
new file mode 100644
index 00000000..c7baacb7
--- /dev/null
+++ b/docs/wails-v3-migration-plan.md
@@ -0,0 +1,123 @@
+# Wails v3 / Go 迁移收尾计划
+
+> 状态：**已完成**（2026-07-31）
+>
+> 本文是收尾验收记录。当前生产实现是 Go + Wails + React；旧脚本和旧测试已删除。Wails 仍为 Alpha，所以发行渠道保持 `technical-preview-unsigned`。
+
+## 1. 目标与边界
+
+- 桌面应用使用 Wails v3，React 只调用生成的 TypeScript bindings。
+- headless CLI 和桌面 service 共用 `internal/` Go 用例。
+- Agent catalog、Provider、安装、配置发现、配置写入、profile、备份、权限和错误契约全部由 Go 实现。
+- 发行工具由 `cmd/oneagent-release` 统一负责；官网只读取 Release 与仓库 JSON。
+- Aider 的上游安装流程可以要求本机 Python 3.12，但这是用户选择 Aider 时的外部前置条件，不是 OneAgent 的构建、测试、运行或发行依赖。
+
+## 2. 最终架构
+
+```text
+React + Vite
+    |
+generated Wails bindings
+    |
+Status / Provider / Agent / Profile services
+    |
+Go application use cases
+    |
+catalog / provider / install / config / profile / securefs / process
+
+cmd/oneagent                 headless CLI
+cmd/oneagent-release         native package + manifest/checks
+cmd/oneagent-rc              locked Agent RC checks
+cmd/oneagent-provider-smoke  Provider protocol RC checks
+site/                        independent Astro release site
+```
+
+生产桌面构建不使用 `server` tag，不监听业务端口。浏览器 E2E 才使用 Wails server/e2e runner。
+
+## 3. 已完成的交付
+
+### 核心迁移
+
+- Go catalog 嵌入并校验 `agents.lock.json`。
+- Go Provider URL、模型发现和三协议 probe。
+- Go 安装编排、npm integrity 校验、registry 白名单和超时取消。
+- Go 配置适配器覆盖 Codex、Claude Code、OpenCode、Kilo CLI、Aider。
+- Go 配置发现、profile/secret 存储、原子写、备份和 Unix/Windows 权限。
+- Wails `StatusService`、`ProviderService`、`AgentService`、`ProfileService`。
+- React 页面和状态层切换到生成 binding；生产代码没有业务 `fetch` 或本地 HTTP API。
+
+### 发行与 RC
+
+- `cmd/oneagent-release` 构建 React、Wails desktop 和纯 Go CLI。
+- 发行包生成 macOS `.app`、Windows/Linux ZIP、源码 ZIP、manifest、SHA-256 和第三方 notices。
+- release check 拒绝 source map、远程资源、secret、Agent 二进制、旧语言 runtime、wheel 和 PyInstaller 文件。
+- `cmd/oneagent-rc verify-agents` 在隔离 HOME/npm prefix 中真实安装锁定 npm Agent，并验证 PATH 和版本。
+- `cmd/oneagent-rc adopted` 将 Codex/Claude Code 指向丢弃端口，区分“配置已采用”和“认证未采用”。
+- `cmd/oneagent-provider-smoke` 复用 Go Provider client 验证 models、Chat、Responses、Anthropic Messages。
+- Docker 和 macOS cleanroom 只运行 Go/Node/shell 验收。
+
+### 清理
+
+已删除：
+
+- 旧 `oneagent/` 实现目录。
+- 旧 Python 测试、RC 脚本、GUI 和发布脚本。
+- `setup.py`、`pyproject.toml`、PyInstaller spec、wheel/resource staging。
+- CI/Docker 中的 setup-python、pip、coverage、PyInstaller 和 wheel 步骤。
+
+## 4. 文件映射
+
+| 旧职责 | 当前实现 |
+| --- | --- |
+| catalog、provider、installer、server | `internal/catalog`、`internal/provider`、`internal/app`、`internal/config` |
+| 本地 GUI | `cmd/oneagent-desktop` + Wails |
+| headless CLI | `cmd/oneagent` |
+| release/build/check/notices | `cmd/oneagent-release` |
+| locked Agent RC | `cmd/oneagent-rc verify-agents` |
+| Provider RC | `cmd/oneagent-provider-smoke` |
+| config adoption RC | `cmd/oneagent-rc adopted` |
+| resource staging | `go:embed` / Wails assets |
+
+## 5. 验收命令
+
+```bash
+go vet ./...
+go test ./...
+go test -race ./...
+
+cd frontend
+npm ci
+npm run test:coverage
+npm run build
+npm run test:e2e
+cd ..
+
+go build -o bin/oneagent ./cmd/oneagent
+bash tests/install_test.sh
+go run ./cmd/oneagent-release build --channel technical-preview-unsigned --source
+go run ./cmd/oneagent-release check release
+```
+
+发行候选在受保护环境执行：
+
+```bash
+go run ./cmd/oneagent-rc verify-agents
+go run ./cmd/oneagent-rc adopted
+go run ./cmd/oneagent-provider-smoke --provider all --timeout 30s
+bash tests/real_install_test.sh
+```
+
+## 6. 最终门禁
+
+- [x] 工作树中不再有受版本控制的旧实现文件。
+- [x] active workflow、Taskfile、Dockerfile 和 README 不调用旧脚本或旧打包工具。
+- [x] Go、React、Astro、Wails binding 和 native smoke 有独立验证入口。
+- [x] 无可选 runtime 的 PATH 下 Go CLI、Go tests、React build 和 release check 可运行。
+- [x] 发行包不含 `.py`、`.pyc`、wheel、PyInstaller 或 Agent 二进制。
+- [x] API Key 不进入 profile、日志、binding、URL 或测试附件。
+- [x] Wails Alpha 阶段只允许 `technical-preview-unsigned`。
+- [x] Aider 的 Python 3.12 只在选择 Aider 安装时作为外部 prerequisite 出现。
+
+## 7. 兼容与回滚
+
+用户的 `~/.oneagent`、Agent 配置路径、profile schema、secret 文件和 backup 命名保持兼容。回滚通过发布上一版已验收的原生包完成，不在新包中恢复已删除的旧 runtime。
diff --git a/frontend/.gitignore b/frontend/.gitignore
index 5453c76f..c046ff1a 100644
--- a/frontend/.gitignore
+++ b/frontend/.gitignore
@@ -1,5 +1,11 @@
 node_modules/
-dist/
+# The bundle is ignored but dist/.keep is not: manifest_embed.go carries a
+# `go:embed all:frontend/dist`, which does not compile when the directory is
+# absent, so a fresh clone could not `go build` or `go vet` before Vite had run.
+# Listed per-entry rather than as `dist/` because excluding the directory itself
+# stops git descending into it, which would make the exception unreachable.
+dist/*
+!dist/.keep
 coverage/
 test-results/
 playwright-report/
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/app/index.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/app/index.ts
new file mode 100644
index 00000000..279015cf
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/app/index.ts
@@ -0,0 +1,12 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+export type {
+    AgentStatus,
+    Capabilities,
+    DetectedConfig,
+    InstallRuntimeResult,
+    ProfileSummary,
+    RuntimeStatus,
+    StatusResponse
+} from "./models.js";
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/app/models.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/app/models.ts
new file mode 100644
index 00000000..9ed981f9
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/app/models.ts
@@ -0,0 +1,99 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as catalog$0 from "../catalog/models.js";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as install$0 from "../install/models.js";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as platform$0 from "../platform/models.js";
+
+export interface AgentStatus {
+    "installed": boolean;
+    "configured": boolean;
+    "guideOnly": boolean;
+    "config": string;
+    "version": string | null;
+    "lockedVersion": string | null;
+    "canInstall": boolean;
+    "provider": string | null;
+    "profileId": string | null;
+    "model": string | null;
+    "baseUrl": string | null;
+    "updatedAt": string | null;
+    "detected": DetectedConfig | null;
+}
+
+export interface Capabilities {
+    "canInstall": { [_ in string]?: boolean } | null;
+
+    /**
+     * MissingRuntime names the runtime an Agent needs before it can be
+     * installed, keyed by Agent id. An entry means canInstall is false only
+     * because a bootstrappable runtime is absent, which the UI turns into a
+     * "install the runtime first" prompt rather than a dead end.
+     */
+    "missingRuntime": { [_ in string]?: string } | null;
+    "supportedAgentIds": string[] | null;
+}
+
+export interface DetectedConfig {
+    "baseUrl": string;
+    "model": string;
+    "managedByOneAgent": boolean;
+    "unreadable": string | null;
+}
+
+/**
+ * InstallRuntimeResult reports what the bootstrap did. PathUpdated is separate
+ * from Installed because an already-downloaded runtime may still need its
+ * directory recorded on the login PATH.
+ */
+export interface InstallRuntimeResult {
+    "runtime": string;
+    "installed": boolean;
+    "version": string;
+    "pathUpdated": boolean;
+    "runtimes": RuntimeStatus[] | null;
+}
+
+/**
+ * ProfileSummary is intentionally a public projection. It has no credential
+ * field; hasKey only reports whether a secret exists in the secure store.
+ */
+export interface ProfileSummary {
+    "id": string;
+    "label": string;
+    "provider": string;
+    "baseUrl": string | null;
+    "model": string | null;
+    "agentIds": string[] | null;
+    "activatedAt": string | null;
+    "hasKey": boolean;
+}
+
+/**
+ * RuntimeStatus is the public projection of one bootstrappable runtime.
+ */
+export type RuntimeStatus = install$0.RuntimeState;
+
+export interface StatusResponse {
+    "apiVersion": number;
+    "platform": platform$0.Info;
+    "capabilities": Capabilities;
+    "agents": { [_ in string]?: AgentStatus } | null;
+    "catalog": catalog$0.CatalogItem[] | null;
+    "groups": catalog$0.Group[] | null;
+    "providers": { [_ in string]?: catalog$0.Provider } | null;
+    "mirrors": catalog$0.Mirror[] | null;
+    "paths": { [_ in string]?: string } | null;
+    "backups": { [_ in string]?: boolean } | null;
+    "profiles": ProfileSummary[] | null;
+    "activeProfile": string | null;
+    "runtimes": RuntimeStatus[] | null;
+    "environment": any;
+    "environmentError": string | null;
+}
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/agentservice.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/agentservice.ts
new file mode 100644
index 00000000..58904d42
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/agentservice.ts
@@ -0,0 +1,18 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import { Call as $Call, CancellablePromise as $CancellablePromise } from "@wailsio/runtime";
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as $models from "./models.js";
+
+export function Activate(request: $models.ActivateRequest): $CancellablePromise<$models.ActivateResponse> {
+    return $Call.ByID(1962001654, request);
+}
+
+export function Install(request: $models.InstallRequest): $CancellablePromise<$models.InstallResponse> {
+    return $Call.ByID(3913480362, request);
+}
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/index.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/index.ts
new file mode 100644
index 00000000..c67de357
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/index.ts
@@ -0,0 +1,34 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+import * as AgentService from "./agentservice.js";
+import * as ProfileService from "./profileservice.js";
+import * as ProviderService from "./providerservice.js";
+import * as RuntimeService from "./runtimeservice.js";
+import * as StatusService from "./statusservice.js";
+export {
+    AgentService,
+    ProfileService,
+    ProviderService,
+    RuntimeService,
+    StatusService
+};
+
+export type {
+    ActivateRequest,
+    ActivateResponse,
+    AgentInstallResult,
+    InstallRequest,
+    InstallResponse,
+    InstallRuntimeRequest,
+    ModelsRequest,
+    ModelsResponse,
+    OpenRegistrationRequest,
+    OpenRegistrationResponse,
+    ProbeRequest,
+    ProbeResponse,
+    ProviderIDRequest,
+    ProviderMutationResponse,
+    SaveProfileRequest,
+    SaveProviderRequest
+} from "./models.js";
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/models.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/models.ts
new file mode 100644
index 00000000..9db5e448
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/models.ts
@@ -0,0 +1,144 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+export interface ActivateRequest {
+    "agent_id": string;
+    "provider": string;
+    "api_base_url": string;
+    "api_key": string;
+    "model": string;
+    "profile_id": string;
+    "small_fast_model": string;
+}
+
+export interface ActivateResponse {
+    "ok": boolean;
+    "agent": string;
+    "config": string;
+    "provider": string;
+    "model": string;
+    "restart": string;
+    "next": string;
+}
+
+export interface AgentInstallResult {
+    "agent": string;
+    "status": string;
+    "config"?: string | null;
+    "installed"?: boolean | null;
+    "version"?: string | null;
+    "lockedVersion"?: string | null;
+    "registry"?: string | null;
+    "code"?: number | null;
+    "error_code"?: string | null;
+    "message"?: string | null;
+    "retryable": boolean;
+}
+
+export interface InstallRequest {
+    "agents": string[] | null;
+    "profile_agents": string[] | null;
+    "provider": string;
+    "api_base_url": string;
+    "api_key": string;
+    "model": string;
+    "small_fast_model": string;
+    "profile_id": string;
+    "configure": boolean;
+    "install_agent": boolean;
+    "locked_version": boolean;
+    "latest": boolean;
+    "skip_test": boolean;
+    "registry": string;
+    "timeout": number;
+}
+
+export interface InstallResponse {
+    "ok": boolean;
+    "code": number;
+    "results": AgentInstallResult[] | null;
+    "log": string;
+    "next": string;
+    "probe": ProbeResponse | null;
+    "probes": { [_ in string]?: ProbeResponse } | null;
+}
+
+export interface InstallRuntimeRequest {
+    "runtime": string;
+}
+
+export interface ModelsRequest {
+    "provider": string;
+    "api_base_url": string;
+    "api_key": string;
+}
+
+export interface ModelsResponse {
+    "ok": boolean;
+    "reachable": boolean;
+    "status": number;
+    "message": string;
+    "error_code": string | null;
+    "retryable": boolean;
+    "protocol"?: string | null;
+    "protocols"?: { [_ in string]?: ProbeResponse } | null;
+    "models": string[] | null;
+}
+
+export interface OpenRegistrationRequest {
+    "provider": string;
+    "agents": string[] | null;
+}
+
+export interface OpenRegistrationResponse {
+    "ok": boolean;
+    "url": string;
+    "message": string;
+}
+
+export interface ProbeRequest {
+    "provider": string;
+    "api_base_url": string;
+    "api_key": string;
+    "model": string;
+    "agents": string[] | null;
+}
+
+export interface ProbeResponse {
+    "ok": boolean;
+    "reachable": boolean;
+    "status": number;
+    "message": string;
+    "error_code": string | null;
+    "retryable": boolean;
+    "protocol"?: string | null;
+    "protocols"?: { [_ in string]?: ProbeResponse } | null;
+}
+
+export interface ProviderIDRequest {
+    "id": string;
+}
+
+export interface ProviderMutationResponse {
+    "ok": boolean;
+}
+
+export interface SaveProfileRequest {
+    "id": string;
+    "label": string;
+    "provider": string;
+    "api_base_url": string;
+    "api_key": string;
+    "model": string;
+    "config_mode": string;
+    "agent_ids": string[] | null;
+}
+
+export interface SaveProviderRequest {
+    "id": string;
+    "name": string;
+    "home": string;
+    "base_url": string;
+    "anthropic_base_url": string;
+    "api_key": string;
+}
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/profileservice.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/profileservice.ts
new file mode 100644
index 00000000..7b851e68
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/profileservice.ts
@@ -0,0 +1,22 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import { Call as $Call, CancellablePromise as $CancellablePromise } from "@wailsio/runtime";
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as app$0 from "../app/models.js";
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as $models from "./models.js";
+
+export function ListProfiles(): $CancellablePromise<app$0.ProfileSummary[] | null> {
+    return $Call.ByID(192725737);
+}
+
+export function SaveProfile(request: $models.SaveProfileRequest): $CancellablePromise<app$0.ProfileSummary> {
+    return $Call.ByID(972252911, request);
+}
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/providerservice.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/providerservice.ts
new file mode 100644
index 00000000..04248a55
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/providerservice.ts
@@ -0,0 +1,38 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import { Call as $Call, CancellablePromise as $CancellablePromise } from "@wailsio/runtime";
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as provider$0 from "../provider/models.js";
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as $models from "./models.js";
+
+export function DeleteProvider(request: $models.ProviderIDRequest): $CancellablePromise<$models.ProviderMutationResponse> {
+    return $Call.ByID(116920211, request);
+}
+
+export function GetProvider(request: $models.ProviderIDRequest): $CancellablePromise<provider$0.Entry> {
+    return $Call.ByID(36265922, request);
+}
+
+export function ListModels(request: $models.ModelsRequest): $CancellablePromise<$models.ModelsResponse> {
+    return $Call.ByID(1201530915, request);
+}
+
+export function OpenRegistration(request: $models.OpenRegistrationRequest): $CancellablePromise<$models.OpenRegistrationResponse> {
+    return $Call.ByID(745368128, request);
+}
+
+export function Probe(request: $models.ProbeRequest): $CancellablePromise<$models.ProbeResponse> {
+    return $Call.ByID(2223638197, request);
+}
+
+export function SaveProvider(request: $models.SaveProviderRequest): $CancellablePromise<provider$0.Entry> {
+    return $Call.ByID(2790810113, request);
+}
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/runtimeservice.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/runtimeservice.ts
new file mode 100644
index 00000000..2240f36b
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/runtimeservice.ts
@@ -0,0 +1,29 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+/**
+ * RuntimeService exposes the Node.js and uv bootstrap. It reuses the install
+ * output listener so the UI shows runtime downloads in the same log pane as
+ * Agent installs.
+ * @module
+ */
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import { Call as $Call, CancellablePromise as $CancellablePromise } from "@wailsio/runtime";
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as app$0 from "../app/models.js";
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as $models from "./models.js";
+
+export function InstallRuntime(request: $models.InstallRuntimeRequest): $CancellablePromise<app$0.InstallRuntimeResult> {
+    return $Call.ByID(2509127327, request);
+}
+
+export function ListRuntimes(): $CancellablePromise<app$0.RuntimeStatus[] | null> {
+    return $Call.ByID(1068151511);
+}
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/statusservice.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/statusservice.ts
new file mode 100644
index 00000000..0d91fc57
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/binding/statusservice.ts
@@ -0,0 +1,14 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import { Call as $Call, CancellablePromise as $CancellablePromise } from "@wailsio/runtime";
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as app$0 from "../app/models.js";
+
+export function GetStatus(): $CancellablePromise<app$0.StatusResponse> {
+    return $Call.ByID(1555230240);
+}
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/catalog/index.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/catalog/index.ts
new file mode 100644
index 00000000..462e2750
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/catalog/index.ts
@@ -0,0 +1,9 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+export type {
+    CatalogItem,
+    Group,
+    Mirror,
+    Provider
+} from "./models.js";
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/catalog/models.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/catalog/models.ts
new file mode 100644
index 00000000..da803d8b
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/catalog/models.ts
@@ -0,0 +1,37 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+export interface CatalogItem {
+    "id": string;
+    "name": string;
+    "group": string;
+    "configMode": string;
+    "guideOnly": boolean;
+    "lockedVersion": string | null;
+    "protocol": string | null;
+    "platforms": string[] | null;
+    "platformNote": string;
+    "rank": number;
+}
+
+export interface Group {
+    "id": string;
+    "name": string;
+}
+
+export interface Mirror {
+    "id": string;
+    "name": string;
+    "registry": string;
+    "upstream": string;
+    "note": string;
+}
+
+export interface Provider {
+    "name": string;
+    "home": string;
+    "base_url": string;
+    "anthropic_base_url"?: string;
+    "custom"?: boolean;
+    "has_key"?: boolean;
+}
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/install/index.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/install/index.ts
new file mode 100644
index 00000000..d00f36fc
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/install/index.ts
@@ -0,0 +1,6 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+export type {
+    RuntimeState
+} from "./models.js";
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/install/models.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/install/models.ts
new file mode 100644
index 00000000..29b01d0d
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/install/models.ts
@@ -0,0 +1,24 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+/**
+ * RuntimeState is the public projection of one managed runtime. It carries no
+ * filesystem paths beyond the managed root so the UI cannot leak a private
+ * directory layout it should not depend on.
+ */
+export interface RuntimeState {
+    "id": string;
+    "name": string;
+    "command": string;
+    "installed": boolean;
+    "version": string;
+    "lockedVersion": string;
+    "managed": boolean;
+    "supported": boolean;
+    "note": string;
+    "license": string;
+    "licenseUrl": string;
+    "source": string;
+    "installPath": string;
+    "requiredByHint"?: string;
+}
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/platform/index.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/platform/index.ts
new file mode 100644
index 00000000..2aad9941
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/platform/index.ts
@@ -0,0 +1,6 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+export type {
+    Info
+} from "./models.js";
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/platform/models.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/platform/models.ts
new file mode 100644
index 00000000..daa33c6d
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/platform/models.ts
@@ -0,0 +1,8 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+export interface Info {
+    "os": string;
+    "arch": string;
+    "shell": string;
+}
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/provider/index.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/provider/index.ts
new file mode 100644
index 00000000..b88297d6
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/provider/index.ts
@@ -0,0 +1,6 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+export type {
+    Entry
+} from "./models.js";
diff --git a/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/provider/models.ts b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/provider/models.ts
new file mode 100644
index 00000000..22164688
--- /dev/null
+++ b/frontend/bindings/github.com/MaimoryLab/OneAgent/internal/provider/models.ts
@@ -0,0 +1,16 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+/**
+ * Entry is the editable local Provider record. APIKey is returned only by the
+ * explicit Provider CRUD service; status projections expose HasKey instead.
+ */
+export interface Entry {
+    "id": string;
+    "name": string;
+    "home": string;
+    "base_url": string;
+    "anthropic_base_url": string;
+    "api_key": string;
+    "built_in": boolean;
+}
diff --git a/frontend/bindings/github.com/wailsapp/wails/v3/internal/eventcreate.ts b/frontend/bindings/github.com/wailsapp/wails/v3/internal/eventcreate.ts
new file mode 100644
index 00000000..1ea10585
--- /dev/null
+++ b/frontend/bindings/github.com/wailsapp/wails/v3/internal/eventcreate.ts
@@ -0,0 +1,9 @@
+//@ts-check
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import { Create as $Create } from "@wailsio/runtime";
+
+Object.freeze($Create.Events);
diff --git a/frontend/bindings/github.com/wailsapp/wails/v3/internal/eventdata.d.ts b/frontend/bindings/github.com/wailsapp/wails/v3/internal/eventdata.d.ts
new file mode 100644
index 00000000..3dd1807b
--- /dev/null
+++ b/frontend/bindings/github.com/wailsapp/wails/v3/internal/eventdata.d.ts
@@ -0,0 +1,2 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
diff --git a/frontend/dist/.keep b/frontend/dist/.keep
new file mode 100644
index 00000000..e69de29b
diff --git a/frontend/e2e/overview.spec.ts b/frontend/e2e/overview.spec.ts
deleted file mode 100644
index fd1bdb13..00000000
--- a/frontend/e2e/overview.spec.ts
+++ /dev/null
@@ -1,271 +0,0 @@
-import { expect, test } from "@playwright/test";
-import type { Page, Route } from "@playwright/test";
-
-import type { AgentStatus, StatusResponse } from "../src/types/api";
-
-const AUTO_AGENTS = ["codex", "claude-code", "opencode", "kilo-cli", "aider"] as const;
-
-function agentStatus(over: Partial<AgentStatus> = {}): AgentStatus {
-  return {
-    installed: true,
-    configured: true,
-    guideOnly: false,
-    config: "/tmp/home/.config",
-    version: "1.0.0",
-    lockedVersion: "1.0.0",
-    canInstall: true,
-    provider: null,
-    model: null,
-    baseUrl: null,
-    updatedAt: null,
-    detected: null,
-    ...over,
-  };
-}
-
-/** Two Agents on different providers — the state per-Agent config exists for. */
-function divergentStatus(): StatusResponse {
-  return {
-    apiVersion: 1,
-    platform: { os: "macos", arch: "arm64", shell: "bash" },
-    capabilities: { canInstall: {}, supportedAgentIds: [...AUTO_AGENTS] },
-    agents: {
-      codex: agentStatus({
-        provider: "ppio",
-        model: "deepseek/deepseek-v3",
-        baseUrl: "https://api.ppio.com/openai",
-        version: "0.144.4",
-        lockedVersion: "0.145.0",
-      }),
-      "claude-code": agentStatus({ provider: "novita", model: "qwen/qwen3-max" }),
-      opencode: agentStatus({ configured: false }),
-      "kilo-cli": agentStatus({ installed: false, configured: false }),
-      aider: agentStatus({ installed: false, configured: false }),
-      cursor: agentStatus({ guideOnly: true, configured: false }),
-    },
-    catalog: [
-      ...AUTO_AGENTS.map((id) => ({
-        id,
-        name: id === "claude-code" ? "Claude Code" : id === "kilo-cli" ? "Kilo CLI" : id[0].toUpperCase() + id.slice(1),
-        group: "auto" as const,
-        configMode: "auto" as const,
-        guideOnly: false,
-        lockedVersion: id === "codex" ? "0.145.0" : "1.0.0",
-        protocol: id === "codex" ? ("responses" as const) : ("openai" as const),
-        platforms: ["macos" as const, "linux" as const, "windows" as const],
-        platformNote: "",
-        rank: { codex: 1, "claude-code": 2, opencode: 4, "kilo-cli": 8, aider: 9 }[id] ?? 99,
-      })),
-      {
-        id: "cursor",
-        name: "Cursor",
-        group: "ide" as const,
-        configMode: "guide" as const,
-        guideOnly: true,
-        lockedVersion: null,
-        protocol: null,
-        platforms: ["macos" as const],
-        platformNote: "按官方文档配置",
-        rank: 3,
-      },
-    ],
-    groups: [
-      { id: "auto", name: "One-click configurable" },
-      { id: "gateway", name: "Gateway agents" },
-      { id: "platform", name: "Official account agents" },
-      { id: "ide", name: "IDE extensions" },
-    ],
-    providers: {
-      ppio: { name: "PPIO", home: "https://ppio.com/", base_url: "https://api.ppio.com/openai" },
-      novita: { name: "Novita", home: "https://novita.ai/", base_url: "https://api.novita.ai/openai" },
-    },
-    mirrors: [],
-    paths: { profile: "/tmp/home/.oneagent/profile.json" },
-    backups: {},
-    environment: null,
-    environmentError: null,
-    profiles: [],
-    activeProfile: null,
-  };
-}
-
-async function fulfillJson(route: Route, body: object, status = 200) {
-  await route.fulfill({ status, contentType: "application/json", body: JSON.stringify(body) });
-}
-
-async function mockOverview(page: Page) {
-  const activateBodies: Record<string, unknown>[] = [];
-  const activatePaths: string[] = [];
-
-  await page.route("**/api/status", (route) => fulfillJson(route, divergentStatus()));
-  await page.route("**/api/probe", (route) =>
-    fulfillJson(route, {
-      ok: true,
-      reachable: true,
-      status: 200,
-      message: "连接测试通过",
-      error_code: null,
-      retryable: false,
-    }),
-  );
-  await page.route("**/api/agents/*/activate", (route) => {
-    activatePaths.push(new URL(route.request().url()).pathname);
-    activateBodies.push(route.request().postDataJSON() as Record<string, unknown>);
-    return fulfillJson(route, {
-      ok: true,
-      agent: "codex",
-      config: "/tmp/home/.codex/config.toml",
-      provider: "novita",
-      model: "qwen/qwen3-max",
-      restart: "Quit any running codex process, then start it again",
-      next: "source ~/.oneagent/agents/codex.env && codex",
-    });
-  });
-  return { activateBodies, activatePaths };
-}
-
-test("总览按 Agent 分别显示各自的 Provider 与模型", async ({ page }, testInfo) => {
-  await mockOverview(page);
-  await page.goto("/#/overview");
-
-  // The whole point of per-Agent config: two Agents, two providers, at once.
-  await expect(page.getByText("PPIO", { exact: false }).first()).toBeVisible();
-  await expect(page.getByText("qwen/qwen3-max")).toBeVisible();
-  await expect(page.getByText("deepseek/deepseek-v3")).toBeVisible();
-
-  // Version drift reads inline on the Agent's own row: it is deferrable
-  // maintenance, not an alert that earns a banner at the top of the page.
-  await expect(page.getByText(/0\.144\.4 → 0\.145\.0/)).toBeVisible();
-  await expect(page.getByText("未配置").first()).toBeVisible();
-
-  await page.screenshot({ path: testInfo.outputPath("overview-per-agent.png"), fullPage: true });
-});
-
-test("配置在 Agent 独立页面完成，成功后给出重启指引", async ({ page }, testInfo) => {
-  const { activateBodies, activatePaths } = await mockOverview(page);
-  await page.goto("/#/overview");
-
-  // Configuring moved off the list: a form inside a row grew the list by its
-  // own height and allowed several rows to sit half-configured at once.
-  const codexRow = page.locator(".agent-manage-row").first();
-  await expect(codexRow.getByLabel("API Key")).toHaveCount(0);
-  await codexRow.click();
-
-  await expect(page).toHaveURL(/#\/agents\/codex$/);
-  await expect(page.getByRole("heading", { name: "Codex" })).toBeVisible();
-  await page.screenshot({ path: testInfo.outputPath("detail-open.png"), fullPage: true });
-
-  const apply = page.getByRole("button", { name: /^应用/ });
-  await expect(apply).toBeDisabled();
-
-  await page.getByLabel("API Key").fill("sentinel-detail-secret");
-  await page.getByRole("button", { name: "测试连接" }).click();
-  await expect(apply).toBeEnabled();
-
-  await apply.click();
-  // An Agent reads its config at startup, so the switch is invisible until the
-  // process restarts; reporting success without that reads as a failure.
-  await expect(page.getByText(/Quit any running codex/)).toBeVisible();
-  await page.screenshot({ path: testInfo.outputPath("detail-applied.png"), fullPage: true });
-
-  expect(activatePaths).toEqual(["/api/agents/codex/activate"]);
-  expect(activateBodies).toHaveLength(1);
-
-  await expect(page.getByLabel("API Key")).toHaveValue("");
-  expect(await page.evaluate(() => ({ local: localStorage.length, session: sessionStorage.length }))).toEqual({
-    local: 0,
-    session: 0,
-  });
-});
-
-test("首屏用于 Agent 列表，而不是横幅与提醒", async ({ page }, testInfo) => {
-  await mockOverview(page);
-  await page.setViewportSize({ width: 1280, height: 860 });
-  await page.goto("/#/overview");
-  await page.waitForSelector(".agent-manage-row");
-
-  // The overview is opened every day, so its first screen belongs to the
-  // Agents. It used to spend 55% of the viewport on a one-off "ready" banner
-  // and a version reminder before the list even started.
-  const list = await page.locator(".agent-manage-list").boundingBox();
-  expect(list).not.toBeNull();
-  expect(list!.y).toBeLessThan(220);
-
-  // The prominent Agents fit without scrolling. Kilo and Aider now sit behind
-  // the disclosure, so the count is the rank<=6 set rather than all five
-  // installable ones.
-  const rows = page.locator(".agent-manage-row");
-  await expect(rows).toHaveCount(4);
-  const last = await rows.last().boundingBox();
-  expect(last!.y + last!.height).toBeLessThan(860);
-
-  // The dismissed banners are gone, not merely moved.
-  await expect(page.getByText("开发环境已就绪")).toHaveCount(0);
-  await expect(page.locator(".overview-notice")).toHaveCount(0);
-
-  await page.screenshot({ path: testInfo.outputPath("overview-first-screen.png") });
-});
-
-test("侧边栏每一项都能真的打开对应页面", async ({ page }, testInfo) => {
-  await mockOverview(page);
-  await page.goto("/#/overview");
-  await page.waitForSelector(".agent-manage-row");
-
-  // Provider and 配置模板 used to point at wizard steps behind SetupGuard, so
-  // clicking them bounced back to step one and looked like a dead link.
-  for (const [label, hash, heading] of [
-    ["Provider", "#/providers", "Provider"],
-    ["配置模板", "#/profiles", "配置模板"],
-    ["环境总览", "#/overview", "环境总览"],
-  ] as const) {
-    await page.getByRole("link", { name: label }).click();
-    await expect(page).toHaveURL(new RegExp(hash.replace("/", "\\/")));
-    await expect(page.getByRole("heading", { name: heading })).toBeVisible();
-    await page.screenshot({ path: testInfo.outputPath(`nav-${heading}.png`), fullPage: true });
-  }
-});
-
-test("Provider 页反查出每个服务正在被哪些 Agent 使用", async ({ page }) => {
-  await mockOverview(page);
-  await page.goto("/#/providers");
-  const ppio = page.getByTestId("provider-ppio");
-  await expect(ppio).toContainText("Codex");
-  const novita = page.getByTestId("provider-novita");
-  await expect(novita).toContainText("Claude Code");
-});
-
-test("首屏按流行度排序，Cursor 在 Kilo 与 Aider 之前", async ({ page }, testInfo) => {
-  await mockOverview(page);
-  await page.goto("/#/overview");
-  await page.waitForSelector(".agent-manage-row");
-
-  // The list is ranked by how widely an Agent is used, not by whether OneAgent
-  // can configure it. Cursor used to be hidden in a footnote while Kilo and
-  // Aider held the top of the page, which misrepresented what people run.
-  const names = await page.locator(".agent-manage-row strong").allTextContents();
-  const order = names.map((n) => n.trim());
-  expect(order.slice(0, 3)).toEqual(["Codex", "Claude Code", "Cursor"]);
-  // Kilo and Aider are not on the first screen at all now; they are behind the
-  // disclosure, which is the whole point of the ranking.
-  expect(order).not.toContain("Kilo CLI");
-  expect(order).not.toContain("Aider");
-  await page.getByRole("button", { name: /其他 Agent/ }).click();
-  const all = (await page.locator(".agent-manage-row strong").allTextContents()).map((n) => n.trim());
-  expect(all.indexOf("Cursor")).toBeLessThan(all.indexOf("Kilo CLI"));
-  expect(all.indexOf("Cursor")).toBeLessThan(all.indexOf("Aider"));
-
-  // A guide-only Agent states how it is obtained rather than offering a form.
-  const cursorRow = page.locator(".agent-manage-row.is-guide").first();
-  await expect(cursorRow).toContainText("按官方文档配置");
-  await expect(cursorRow.getByLabel("API Key")).toHaveCount(0);
-
-  await page.screenshot({ path: testInfo.outputPath("overview-ranked.png"), fullPage: true });
-});
-
-test("已配置的环境直接进入总览而不是向导", async ({ page }) => {
-  await mockOverview(page);
-  await page.goto("/");
-  // A returning user should not be sent back through first-run setup.
-  await expect(page).toHaveURL(/#\/overview$/);
-  await expect(page.getByRole("heading", { name: "环境总览" })).toBeVisible();
-});
diff --git a/frontend/e2e/wails-server.mjs b/frontend/e2e/wails-server.mjs
new file mode 100644
index 00000000..2f6e1965
--- /dev/null
+++ b/frontend/e2e/wails-server.mjs
@@ -0,0 +1,32 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const frontendDir = dirname(fileURLToPath(import.meta.url));
+const root = join(frontendDir, "..", "..");
+const home = await mkdtemp(join(tmpdir(), "oneagent-wails-e2e-"));
+const child = spawn("go", ["run", "-tags", "wails,server,e2e", "./cmd/oneagent-desktop"], {
+  cwd: root,
+  env: {
+    ...process.env,
+    ONEAGENT_HOME: home,
+  },
+  stdio: "inherit",
+});
+
+let stopping = false;
+const stop = () => {
+  if (!stopping) {
+    stopping = true;
+    child.kill();
+  }
+};
+
+process.once("SIGINT", stop);
+process.once("SIGTERM", stop);
+child.once("exit", async (code) => {
+  await rm(home, { recursive: true, force: true });
+  process.exit(code ?? 1);
+});
diff --git a/frontend/e2e/wails.spec.ts b/frontend/e2e/wails.spec.ts
new file mode 100644
index 00000000..fa4b0f38
--- /dev/null
+++ b/frontend/e2e/wails.spec.ts
@@ -0,0 +1,72 @@
+import { expect, test } from "@playwright/test";
+
+test("language selection switches to English and persists", async ({ page }) => {
+  await page.goto("/");
+  await page.getByRole("combobox", { name: "语言" }).selectOption("en");
+  await expect(page.getByRole("heading", { name: "Environment overview" })).toBeVisible();
+
+  await page.reload();
+  await expect(page.getByRole("combobox", { name: "Language" })).toHaveValue("en");
+});
+
+test("Profile management applies an environment and the overview stays read-only", async ({ page }) => {
+  const bindingMethodIDs = new Set<number>();
+  page.on("request", (request) => {
+    const path = new URL(request.url()).pathname;
+    if (request.method() !== "POST" || path !== "/wails/runtime") return;
+    const call = request.postDataJSON() as { args?: { methodID?: unknown } };
+    if (typeof call.args?.methodID === "number") bindingMethodIDs.add(call.args.methodID);
+  });
+
+  await page.goto("/");
+  await expect(page.getByRole("heading", { name: "环境总览" })).toBeVisible();
+  await expect(page.getByText("尚未安装任何 Agent")).toBeVisible();
+  await expect(page.getByRole("button", { name: /开始配置|新建配置/ })).toHaveCount(0);
+
+  await page.getByRole("link", { name: "配置模板" }).click();
+  await page.getByRole("button", { name: "新增 Profile" }).click();
+  await page.getByLabel("Profile ID").fill("team-ppio");
+  await page.getByLabel("名称").fill("团队 PPIO");
+  await page.getByLabel("模型", { exact: true }).fill("oneagent-e2e-model");
+  await page.getByLabel("API Key").fill("e2e-key");
+  await page.getByLabel("选择 Codex").check();
+  await page.getByRole("button", { name: "保存 Profile" }).click();
+
+  const profile = page.getByTestId("profile-team-ppio");
+  await expect(profile).toContainText("团队 PPIO");
+  await profile.getByRole("button", { name: "编辑 团队 PPIO" }).click();
+  await page.getByLabel("名称").fill("团队默认");
+  await page.getByRole("button", { name: "保存 Profile" }).click();
+  await expect(profile).toContainText("团队默认");
+  await profile.getByRole("button", { name: "应用到 Agent" }).click();
+  await expect(page.getByText(/已应用到 1 个 Agent/)).toBeVisible();
+
+  await page.getByRole("link", { name: "激活环境" }).click();
+  await expect(page.getByRole("heading", { name: "环境总览" })).toBeVisible();
+  const agent = page.getByTestId("agent-codex");
+  await expect(agent).toContainText("PPIO");
+  await expect(agent).toContainText("团队默认");
+  expect(bindingMethodIDs.size).toBeGreaterThanOrEqual(3);
+});
+
+test("Provider CRUD persists keys", async ({ page }) => {
+  await page.goto("/");
+  await page.getByRole("link", { name: "Provider" }).click();
+  await page.getByRole("button", { name: "新增 Provider" }).click();
+  await expect(page.getByLabel("Provider ID")).toBeVisible();
+  await page.getByLabel("Provider ID").fill("acme");
+  await page.getByLabel("名称").fill("Acme");
+  await page.getByLabel("OpenAI 兼容 Base URL").fill("https://api.acme.test/openai");
+  await page.getByLabel("API Key").fill("sk-acme");
+  await page.getByRole("button", { name: "保存", exact: true }).click();
+
+  const card = page.getByTestId("provider-acme");
+  await expect(card).toContainText("已保存 Key");
+  await page.getByRole("button", { name: "编辑 Acme" }).click();
+  await expect(page.getByLabel("API Key")).toHaveValue("sk-acme");
+  await page.getByRole("button", { name: "关闭编辑" }).click();
+
+  page.once("dialog", (dialog) => void dialog.accept());
+  await page.getByRole("button", { name: "删除 Acme" }).click();
+  await expect(page.getByTestId("provider-acme")).toHaveCount(0);
+});
diff --git a/frontend/e2e/wizard.spec.ts b/frontend/e2e/wizard.spec.ts
deleted file mode 100644
index d82a0256..00000000
--- a/frontend/e2e/wizard.spec.ts
+++ /dev/null
@@ -1,318 +0,0 @@
-import { expect, test, type Page, type Route } from "@playwright/test";
-
-import type {
-  AgentCatalogItem,
-  InstallResponse,
-  ModelsResponse,
-  ProbeResponse,
-  StatusResponse,
-} from "../src/types/api";
-
-// Typed so tsc flags drift between these mocks and the real API contract; the
-// protocol values mirror ADAPTER_PROTOCOLS in oneagent/catalog.py.
-const catalog: AgentCatalogItem[] = [
-  { rank: 1, id: "codex", name: "Codex", group: "auto", configMode: "auto", guideOnly: false, lockedVersion: "0.145.0", protocol: "responses", platforms: ["macos", "linux", "windows"], platformNote: "" },
-  { rank: 2, id: "claude-code", name: "Claude Code", group: "auto", configMode: "auto", guideOnly: false, lockedVersion: "2.1.217", protocol: "anthropic", platforms: ["macos", "linux", "windows"], platformNote: "" },
-  { rank: 4, id: "opencode", name: "OpenCode", group: "auto", configMode: "auto", guideOnly: false, lockedVersion: "1.18.4", protocol: "openai", platforms: ["macos", "linux", "windows"], platformNote: "" },
-  { rank: 8, id: "kilo-cli", name: "Kilo CLI", group: "auto", configMode: "auto", guideOnly: false, lockedVersion: "7.4.11", protocol: "openai", platforms: ["macos", "linux", "windows"], platformNote: "" },
-  { rank: 9, id: "aider", name: "Aider", group: "auto", configMode: "auto", guideOnly: false, lockedVersion: "0.86.2", protocol: "openai", platforms: ["macos", "linux", "windows"], platformNote: "" },
-  { rank: 5, id: "openclaw", name: "OpenClaw", group: "gateway", configMode: "guide", guideOnly: true, lockedVersion: null, protocol: null, platforms: ["macos", "linux", "windows"], platformNote: "" },
-  { rank: 3, id: "cursor", name: "Cursor", group: "platform", configMode: "guide", guideOnly: true, lockedVersion: null, protocol: null, platforms: ["macos", "linux", "windows"], platformNote: "" },
-  { rank: 11, id: "cline", name: "Cline", group: "ide", configMode: "guide", guideOnly: true, lockedVersion: null, protocol: null, platforms: ["macos", "linux", "windows"], platformNote: "" },
-];
-
-const agentStatuses = Object.fromEntries(
-  catalog.map((agent, index) => [
-    agent.id,
-    {
-      installed: index === 0 || index === 2,
-      configured: false,
-      guideOnly: agent.guideOnly,
-      config: agent.guideOnly ? "" : `/tmp/home/.config/${agent.id}`,
-      version: index === 0 || index === 2 ? agent.lockedVersion : null,
-      lockedVersion: agent.lockedVersion,
-      canInstall: !agent.guideOnly,
-      provider: null,
-      model: null,
-      baseUrl: null,
-      updatedAt: null,
-      detected: null,
-    },
-  ]),
-);
-
-function statusPayload(activated: boolean): StatusResponse {
-  return {
-    apiVersion: 1,
-    platform: { os: "macos", arch: "arm64", shell: "bash" },
-    capabilities: { canInstall: {}, supportedAgentIds: catalog.map((agent) => agent.id) },
-    agents: agentStatuses,
-    catalog,
-    groups: [
-      { id: "auto", name: "One-click configurable" },
-      { id: "gateway", name: "Gateway agents" },
-      { id: "platform", name: "Official account agents" },
-      { id: "ide", name: "IDE extensions" },
-    ],
-    providers: {
-      ppio: { name: "PPIO", home: "https://ppio.com/", base_url: "https://api.ppio.com/openai" },
-      novita: { name: "Novita", home: "https://novita.ai/", base_url: "https://api.novita.ai/openai" },
-    },
-    mirrors: [],
-    paths: {
-      profile: "/tmp/home/.oneagent/profile.json",
-      codex_config: "/tmp/home/.codex/config.toml",
-      "claude-code_config": "/tmp/home/.claude/settings.json",
-      opencode_config: "/tmp/home/.config/opencode/opencode.jsonc",
-    },
-    backups: {},
-    environment: activated
-      ? {
-          schema_version: 1,
-          provider: "ppio",
-          base_url: "https://api.ppio.com/openai",
-          model: "deepseek-v3",
-          config_mode: "provider",
-          agent_ids: ["codex", "claude-code", "opencode"],
-          activated_at: "2026-07-22T00:00:00Z",
-        }
-      : null,
-    environmentError: null,
-    profiles: [],
-    activeProfile: null,
-  };
-}
-
-async function fulfillJson(route: Route, body: object, status = 200) {
-  await route.fulfill({ status, contentType: "application/json", body: JSON.stringify(body) });
-}
-
-async function mockApi(page: Page, options: { failFirstInstall?: boolean } = {}) {
-  let activated = false;
-  let installCalls = 0;
-  const installBodies: Record<string, unknown>[] = [];
-  const probeBodies: Record<string, unknown>[] = [];
-  const modelBodies: Record<string, unknown>[] = [];
-
-  await page.route("**/api/status", (route) => fulfillJson(route, statusPayload(activated)));
-  await page.route("**/api/probe", (route) => {
-    probeBodies.push(route.request().postDataJSON() as Record<string, unknown>);
-    return fulfillJson(route, { ok: true, reachable: true, status: 200, message: "连接测试通过", error_code: null, retryable: false } satisfies ProbeResponse);
-  });
-  await page.route("**/api/models", (route) => {
-    modelBodies.push(route.request().postDataJSON() as Record<string, unknown>);
-    return fulfillJson(route, { ok: true, reachable: true, status: 200, message: "Found 2 models.", error_code: null, retryable: false, models: ["deepseek-v3", "qwen3-coder"] } satisfies ModelsResponse);
-  });
-  await page.route("**/api/open-register", (route) => fulfillJson(route, { ok: true, url: "https://ppio.com/", message: "opened" }));
-  await page.route("**/api/install", async (route) => {
-    installCalls += 1;
-    const body = route.request().postDataJSON() as Record<string, unknown>;
-    installBodies.push(body);
-    await new Promise((resolve) => setTimeout(resolve, 120));
-    const agents = body.agents as string[];
-    if (options.failFirstInstall && installCalls === 1) {
-      await fulfillJson(route, {
-        ok: false,
-        code: 3,
-        results: agents.map((agent, index) =>
-          index === 0
-            ? { agent, status: "failed" as const, error_code: "PREREQUISITE_MISSING", message: "npm is required", retryable: true }
-            : { agent, status: "configured" as const, retryable: false },
-        ),
-        log: "redacted install log",
-        next: "",
-        probe: null,
-      } satisfies InstallResponse);
-      return;
-    }
-    activated = true;
-    await fulfillJson(route, {
-      ok: true,
-      code: 0,
-      results: agents.map((agent) => ({ agent, status: body.configure ? ("configured" as const) : ("skipped" as const), retryable: false })),
-      log: "redacted install log",
-      next: "source ~/.oneagent/agents/codex.env && codex",
-      probe: body.configure
-        ? { ok: true, reachable: true, status: 200, message: "Connection test passed.", error_code: null, retryable: false }
-        : null,
-    } satisfies InstallResponse);
-  });
-
-  return { installBodies, modelBodies, probeBodies };
-}
-
-async function expectNoHorizontalOverflow(page: Page) {
-  const sizes = await page.evaluate(() => ({ body: document.body.scrollWidth, viewport: window.innerWidth }));
-  expect(sizes.body).toBeLessThanOrEqual(sizes.viewport);
-}
-
-for (const viewport of [
-  { width: 1440, height: 900, label: "1440x900" },
-  { width: 1280, height: 800, label: "1280x800" },
-  { width: 1024, height: 720, label: "1024x720" },
-]) {
-  test(`完整七页流程 ${viewport.label}`, async ({ page }, testInfo) => {
-    await page.setViewportSize(viewport);
-    await mockApi(page);
-    await page.goto("/#/setup/agents");
-    await expect(page.getByRole("heading", { name: "选择 Agent" })).toBeVisible();
-    // Ranked, not grouped: leading with the "auto" group used to put Kilo and
-    // Aider here and fold Cursor and OpenClaw out of sight.
-    await expect(page.locator(".agent-row input[type=checkbox]").first()).toHaveAttribute(
-      "aria-label",
-      "选择 Codex",
-    );
-    const firstScreen = await page.locator(".content-section .agent-row").allTextContents();
-    expect(firstScreen.join(" ")).toContain("Cursor");
-    expect(firstScreen.join(" ")).not.toContain("Aider");
-    // Guide-only rows stay selectable; install_many answers them with a guide.
-    await expect(page.getByRole("checkbox", { name: "选择 Cursor" })).toBeEnabled();
-    await page.screenshot({ path: testInfo.outputPath(`01-agents-${viewport.label}.png`) });
-    await expectNoHorizontalOverflow(page);
-
-    await page.getByRole("checkbox", { name: "选择 Codex" }).check();
-    await page.getByRole("checkbox", { name: "选择 Claude Code" }).check();
-    await page.getByRole("checkbox", { name: "选择 OpenCode" }).check();
-    await page.getByRole("button", { name: "继续" }).click();
-    await expect(page.getByRole("heading", { name: "配置方式" })).toBeVisible();
-    await page.screenshot({ path: testInfo.outputPath(`02-mode-${viewport.label}.png`) });
-    await expectNoHorizontalOverflow(page);
-
-    await page.getByRole("button", { name: /配置模型服务/ }).click();
-    await page.getByRole("button", { name: "继续" }).click();
-    await expect(page.getByRole("heading", { name: "连接模型服务" })).toBeVisible();
-    // The endpoint note must aggregate the protocols of the selected Agents.
-    await expect(page.getByText(/Anthropic Messages \+ OpenAI Chat Completions \+ OpenAI Responses/)).toBeVisible();
-    await page.getByLabel("API Key").fill("sentinel-browser-secret");
-    await page.getByRole("button", { name: "测试连接" }).click();
-    await expect(page.getByText("连接测试通过")).toBeVisible();
-    await page.screenshot({ path: testInfo.outputPath(`03-provider-${viewport.label}.png`) });
-    await expectNoHorizontalOverflow(page);
-
-    await page.getByRole("button", { name: "继续选择模型" }).click();
-    await expect(page.getByRole("heading", { name: "选择模型" })).toBeVisible();
-    await expect(page.getByRole("radio", { name: /deepseek-v3/ })).toBeChecked();
-    await page.screenshot({ path: testInfo.outputPath(`04-model-${viewport.label}.png`) });
-    await expectNoHorizontalOverflow(page);
-
-    await page.getByRole("button", { name: "继续" }).click();
-    await expect(page.getByRole("heading", { name: "确认激活" })).toBeVisible();
-    await page.screenshot({ path: testInfo.outputPath(`05-review-${viewport.label}.png`) });
-    await expectNoHorizontalOverflow(page);
-
-    await page.getByRole("button", { name: "开始激活" }).click();
-    await expect(page.getByRole("heading", { name: "激活完成" })).toBeVisible();
-    await page.screenshot({ path: testInfo.outputPath(`06-result-${viewport.label}.png`) });
-    await expectNoHorizontalOverflow(page);
-    expect(await page.evaluate(() => ({ local: localStorage.length, session: sessionStorage.length }))).toEqual({ local: 0, session: 0 });
-    expect(await page.content()).not.toContain("sentinel-browser-secret");
-
-    await page.getByRole("button", { name: "进入总览" }).click();
-    // Arriving at the overview is what matters here. The old assertion looked
-    // for a "ready" banner, which was a one-off wizard confirmation occupying
-    // the top of a page the user opens every day; the Agent list is the page.
-    await expect(page.getByRole("heading", { name: "环境总览" })).toBeVisible();
-    await expect(page.locator(".agent-manage-row").first()).toBeVisible();
-    await page.screenshot({ path: testInfo.outputPath(`07-overview-${viewport.label}.png`) });
-    await expectNoHorizontalOverflow(page);
-  });
-}
-
-test("浏览器后退到激活页不重放安装", async ({ page }) => {
-  const mock = await mockApi(page);
-  await page.goto("/#/setup/agents");
-  await page.getByRole("checkbox", { name: "选择 Codex" }).check();
-  await page.getByRole("button", { name: "继续" }).click();
-  await page.getByRole("button", { name: /配置模型服务/ }).click();
-  await page.getByRole("button", { name: "继续" }).click();
-  await page.getByLabel("API Key").fill("backtrack-secret");
-  await page.getByRole("button", { name: "测试连接" }).click();
-  await expect(page.getByText("连接测试通过")).toBeVisible();
-  await page.getByRole("button", { name: "继续选择模型" }).click();
-  await expect(page.getByRole("heading", { name: "选择模型" })).toBeVisible();
-  await page.getByRole("button", { name: "继续" }).click();
-  await page.getByRole("button", { name: "开始激活" }).click();
-  await expect(page.getByRole("heading", { name: "激活完成" })).toBeVisible();
-  await page.getByRole("button", { name: "进入总览" }).click();
-  await expect(page.getByRole("heading", { name: "环境总览" })).toBeVisible();
-
-  await page.goBack();
-  // The outcome page must come back as a static summary: same heading, no
-  // second /api/install fired with the (now cleared) key.
-  await expect(page.getByRole("heading", { name: "激活完成" })).toBeVisible();
-  await page.waitForTimeout(300);
-  expect(mock.installBodies).toHaveLength(1);
-});
-
-test("已有账号路径跳过 Provider 和模型", async ({ page }) => {
-  const mock = await mockApi(page);
-  await page.goto("/#/setup/agents");
-  await page.getByRole("checkbox", { name: "选择 Codex" }).check();
-  await page.getByRole("button", { name: "继续" }).click();
-  await page.getByRole("button", { name: /使用已有账号或配置/ }).click();
-  await page.getByRole("button", { name: "继续" }).click();
-  await expect(page.getByRole("heading", { name: "确认激活" })).toBeVisible();
-  await expect(page.getByText("已跳过")).toHaveCount(2);
-  await page.getByRole("button", { name: "开始激活" }).click();
-  await expect(page.getByRole("heading", { name: "激活完成" })).toBeVisible();
-  expect(mock.installBodies[0]).toMatchObject({ configure: false, api_key: "", agents: ["codex"] });
-});
-
-test("切回内置 Provider 后不提交残留 Custom URL", async ({ page }) => {
-  const mock = await mockApi(page);
-  await page.goto("/#/setup/agents");
-  await page.getByRole("checkbox", { name: "选择 Codex" }).check();
-  await page.getByRole("button", { name: "继续" }).click();
-  await page.getByRole("button", { name: /配置模型服务/ }).click();
-  await page.getByRole("button", { name: "继续" }).click();
-  await expect(page.getByRole("heading", { name: "连接模型服务" })).toBeVisible();
-  await page.getByRole("radio", { name: "自定义", exact: true }).click();
-  await page.getByLabel("Base URL").fill("http://127.0.0.1:9900/openai");
-  await page.getByRole("radio", { name: "PPIO", exact: true }).click();
-  await page.getByLabel("API Key").fill("provider-switch-secret");
-  await page.getByRole("button", { name: "测试连接" }).click();
-  await expect(page.getByText("连接测试通过")).toBeVisible();
-  await page.getByRole("button", { name: "继续选择模型" }).click();
-  await expect(page.getByRole("heading", { name: "选择模型" })).toBeVisible();
-  await page.getByRole("button", { name: "继续" }).click();
-  await page.getByRole("button", { name: "开始激活" }).click();
-  await expect(page.getByRole("heading", { name: "激活完成" })).toBeVisible();
-  expect(mock.probeBodies[0]).toMatchObject({ provider: "ppio", api_base_url: "" });
-  expect(mock.modelBodies[0]).toMatchObject({ provider: "ppio", api_base_url: "" });
-  expect(mock.installBodies[0]).toMatchObject({ provider: "ppio", api_base_url: "" });
-});
-
-test("失败 Agent 可以单独重试且不重复成功项", async ({ page }) => {
-  const mock = await mockApi(page, { failFirstInstall: true });
-  await page.goto("/#/setup/agents");
-  await page.getByRole("checkbox", { name: "选择 Codex" }).check();
-  await page.getByRole("checkbox", { name: "选择 OpenCode" }).check();
-  await page.getByRole("button", { name: "继续" }).click();
-  await page.getByRole("button", { name: /配置模型服务/ }).click();
-  await page.getByRole("button", { name: "继续" }).click();
-  await page.getByLabel("API Key").fill("retry-secret");
-  await page.getByRole("button", { name: "测试连接" }).click();
-  await expect(page.getByText("连接测试通过")).toBeVisible();
-  await page.getByRole("button", { name: "继续选择模型" }).click();
-  await expect(page.getByRole("heading", { name: "选择模型" })).toBeVisible();
-  await page.getByRole("button", { name: "继续" }).click();
-  await page.getByRole("button", { name: "开始激活" }).click();
-  await expect(page.getByRole("heading", { name: "需要处理部分问题" })).toBeVisible();
-  await page.getByRole("button", { name: "重试" }).click();
-  await expect(page.getByRole("heading", { name: "激活完成" })).toBeVisible();
-  expect(mock.installBodies).toHaveLength(2);
-  expect(mock.installBodies[1]).toMatchObject({ agents: ["codex"], profile_agents: ["codex", "opencode"] });
-});
-
-test("未配置时根路径展示着陆页，且入口通向向导", async ({ page }) => {
-  // The landing page exists for someone who has not configured anything. A
-  // returning user is sent to their own overview instead (overview.spec.ts
-  // covers that half); this is the other side of the same decision.
-  await mockApi(page);
-  await page.goto("/");
-  await expect(page.getByRole("link", { name: /Open OneAgent/ }).first()).toBeVisible();
-  // It renders as its own document, not inside the app's window chrome.
-  await expect(page.locator(".app-window")).toHaveCount(0);
-  await page.getByRole("link", { name: /Open workspace/ }).first().click();
-  await expect(page.getByRole("heading", { name: "选择 Agent" })).toBeVisible();
-});
diff --git a/frontend/index.html b/frontend/index.html
index dd20cb9e..8b6de84b 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -3,8 +3,9 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="color-scheme" content="light" />
-    <meta name="theme-color" content="#f5f5f7" />
+    <meta name="color-scheme" content="light dark" />
+    <meta name="theme-color" content="#f5f5f7" media="(prefers-color-scheme: light)" />
+    <meta name="theme-color" content="#151517" media="(prefers-color-scheme: dark)" />
     <meta name="description" content="OneAgent is the calm control plane for coding agents, providers, models, and profiles." />
     <title>OneAgent — every agent, one clear lane</title>
   </head>
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 41bc8865..2ee89d6a 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -8,6 +8,7 @@
       "name": "oneagent-frontend",
       "version": "0.2.0-dev",
       "dependencies": {
+        "@wailsio/runtime": "3.0.0-alpha2.117",
         "lucide-react": "1.25.0",
         "react": "19.2.8",
         "react-dom": "19.2.8",
@@ -1399,6 +1400,12 @@
         "url": "https://opencollective.com/vitest"
       }
     },
+    "node_modules/@wailsio/runtime": {
+      "version": "3.0.0-alpha2.117",
+      "resolved": "https://registry.npmjs.org/@wailsio/runtime/-/runtime-3.0.0-alpha2.117.tgz",
+      "integrity": "sha512-RZr6cncIXjdTbn2IqJ6AZXPm9WooaZEsNlNfaUH+Ru/YlH5sKDDeRdWpbcvsgoMLh4AJ+O8aBzZEiTYWDipGxw==",
+      "license": "MIT"
+    },
     "node_modules/ansi-regex": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index 07f683fc..13d7b653 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -10,9 +10,10 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
-    "e2e": "playwright test"
+    "test:e2e": "playwright test"
   },
   "dependencies": {
+    "@wailsio/runtime": "3.0.0-alpha2.117",
     "lucide-react": "1.25.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",
diff --git a/frontend/playwright.config.ts b/frontend/playwright.config.ts
index f46b8cdd..cff213da 100644
--- a/frontend/playwright.config.ts
+++ b/frontend/playwright.config.ts
@@ -1,31 +1,23 @@
 import { defineConfig } from "@playwright/test";
 
-const pythonCommand = process.platform === "win32" ? "python ..\\scripts\\gui.py --port 8765 --no-open" : "python3 ../scripts/gui.py --port 8765 --no-open";
+const port = Number(process.env.ONEAGENT_E2E_PORT || 34123);
 
 export default defineConfig({
   testDir: "./e2e",
-  fullyParallel: false,
-  timeout: 30_000,
-  expect: { timeout: 5_000 },
-  reporter: [["list"]],
+  workers: 1,
   use: {
-    baseURL: "http://127.0.0.1:8765",
-    browserName: "chromium",
+    baseURL: `http://127.0.0.1:${port}`,
+    locale: "zh-CN",
     trace: "retain-on-failure",
-    screenshot: "only-on-failure",
   },
   webServer: {
-    command: pythonCommand,
-    cwd: process.cwd(),
-    url: "http://127.0.0.1:8765/",
-    reuseExistingServer: true,
-    timeout: 30_000,
-    // Surface the Python GUI's own output. Without this a webServer startup
-    // failure reports only "Timed out waiting 30000ms" with no cause.
-    stdout: "pipe",
-    stderr: "pipe",
+    command: "npm run build && node ./e2e/wails-server.mjs",
+    url: `http://127.0.0.1:${port}/health`,
+    timeout: 120_000,
+    reuseExistingServer: false,
     env: {
-      ONEAGENT_DISABLE_BROWSER: "1",
+      WAILS_SERVER_HOST: "127.0.0.1",
+      WAILS_SERVER_PORT: String(port),
     },
   },
 });
diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml
new file mode 100644
index 00000000..84156855
--- /dev/null
+++ b/frontend/pnpm-lock.yaml
@@ -0,0 +1,1933 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      '@wailsio/runtime':
+        specifier: 3.0.0-alpha2.117
+        version: 3.0.0-alpha2.117
+      lucide-react:
+        specifier: 1.25.0
+        version: 1.25.0(react@19.2.8)
+      react:
+        specifier: 19.2.8
+        version: 19.2.8
+      react-dom:
+        specifier: 19.2.8
+        version: 19.2.8(react@19.2.8)
+      react-router-dom:
+        specifier: 7.18.1
+        version: 7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+    devDependencies:
+      '@playwright/test':
+        specifier: 1.61.1
+        version: 1.61.1
+      '@testing-library/jest-dom':
+        specifier: 7.0.0
+        version: 7.0.0(@testing-library/dom@10.4.1)
+      '@testing-library/react':
+        specifier: 16.3.2
+        version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+      '@testing-library/user-event':
+        specifier: 14.6.1
+        version: 14.6.1(@testing-library/dom@10.4.1)
+      '@types/node':
+        specifier: 26.1.1
+        version: 26.1.1
+      '@types/react':
+        specifier: 19.2.17
+        version: 19.2.17
+      '@types/react-dom':
+        specifier: 19.2.3
+        version: 19.2.3(@types/react@19.2.17)
+      '@vitejs/plugin-react':
+        specifier: 6.0.3
+        version: 6.0.3(vite@8.1.5(@types/node@26.1.1))
+      '@vitest/coverage-v8':
+        specifier: 4.1.10
+        version: 4.1.10(vitest@4.1.10)
+      jsdom:
+        specifier: 29.1.1
+        version: 29.1.1
+      typescript:
+        specifier: 7.0.2
+        version: 7.0.2
+      vite:
+        specifier: 8.1.5
+        version: 8.1.5(@types/node@26.1.1)
+      vitest:
+        specifier: 4.1.10
+        version: 4.1.10(@types/node@26.1.1)(@vitest/coverage-v8@4.1.10)(jsdom@29.1.1)(vite@8.1.5(@types/node@26.1.1))
+
+packages:
+
+  '@adobe/css-tools@4.5.0':
+    resolution: {integrity: sha512-6OzddxPio9UiWTCemp4N8cYLV2ZN1ncRnV1cVGtve7dhPOtRkleRyx32GQCYSwDYgaHU3USMm84tNsvKzRCa1Q==}
+
+  '@asamuzakjp/css-color@5.1.11':
+    resolution: {integrity: sha512-KVw6qIiCTUQhByfTd78h2yD1/00waTmm9uy/R7Ck/ctUyAPj+AEDLkQIdJW0T8+qGgj3j5bpNKK7Q3G+LedJWg==}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  '@asamuzakjp/dom-selector@7.1.1':
+    resolution: {integrity: sha512-67RZDnYRc8H/8MLDgQCDE//zoqVFwajkepHZgmXrbwybzXOEwOWGPYGmALYl9J2DOLfFPPs6kKCqmbzV895hTQ==}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  '@asamuzakjp/generational-cache@1.0.1':
+    resolution: {integrity: sha512-wajfB8KqzMCN2KGNFdLkReeHncd0AslUSrvHVvvYWuU8ghncRJoA50kT3zP9MVL0+9g4/67H+cdvBskj9THPzg==}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  '@asamuzakjp/nwsapi@2.3.9':
+    resolution: {integrity: sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==}
+
+  '@babel/code-frame@7.29.7':
+    resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-string-parser@7.29.7':
+    resolution: {integrity: sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-identifier@7.29.7':
+    resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/parser@7.29.7':
+    resolution: {integrity: sha512-hnORnjP/1P/zFEndoeX+n+t1RwWRJiJpM/jO7FW32Kn9r5+sJB2JWOdYo4L6k78j15eCwY3Gm/7364B1EMwtNg==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  '@babel/runtime@7.29.7':
+    resolution: {integrity: sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/types@7.29.7':
+    resolution: {integrity: sha512-4zBIxpPzowiZpusoFkyGVwakdRJUyuH5PxQ/PrqghfdFWWasvnCdPfQXHrenDai+gyLARulZjZowCOj6fjT4pA==}
+    engines: {node: '>=6.9.0'}
+
+  '@bcoe/v8-coverage@1.0.2':
+    resolution: {integrity: sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==}
+    engines: {node: '>=18'}
+
+  '@bramus/specificity@2.4.2':
+    resolution: {integrity: sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==}
+    hasBin: true
+
+  '@csstools/color-helpers@6.1.0':
+    resolution: {integrity: sha512-064IFJdjTfUqnjpCVpMOdbr8FLQBhinbZj6yRv2An2E41O/pLEXqfFRWqGq/SxlE5PEUYTlvWsG2r8MswAVvkg==}
+    engines: {node: '>=20.19.0'}
+
+  '@csstools/css-calc@3.3.0':
+    resolution: {integrity: sha512-c5ihYsPkdG6JCkU2zTMm4+k6r7RXuGxtWYhu5DHMIiF1FHzrfmHL5so11AoFpUv/tu61xfcmT4AmKoFfMPoqdQ==}
+    engines: {node: '>=20.19.0'}
+    peerDependencies:
+      '@csstools/css-parser-algorithms': ^4.0.0
+      '@csstools/css-tokenizer': ^4.0.0
+
+  '@csstools/css-color-parser@4.1.10':
+    resolution: {integrity: sha512-UZhQLIUyJaaMepqehrCODwCg2KW25vFvLWBmqYFaPclYvvxzj/sG8LBOhBFCp11i9uE7t1EyS+RAoV9tztPFyw==}
+    engines: {node: '>=20.19.0'}
+    peerDependencies:
+      '@csstools/css-parser-algorithms': ^4.0.0
+      '@csstools/css-tokenizer': ^4.0.0
+
+  '@csstools/css-parser-algorithms@4.0.0':
+    resolution: {integrity: sha512-+B87qS7fIG3L5h3qwJ/IFbjoVoOe/bpOdh9hAjXbvx0o8ImEmUsGXN0inFOnk2ChCFgqkkGFQ+TpM5rbhkKe4w==}
+    engines: {node: '>=20.19.0'}
+    peerDependencies:
+      '@csstools/css-tokenizer': ^4.0.0
+
+  '@csstools/css-syntax-patches-for-csstree@1.1.7':
+    resolution: {integrity: sha512-fQ+05118eQS1cofO3aJpB5efgpBZMvIzwr/sbC8kDLVA5XLG8q1kJV5yzrUAI1f7lvhPnm8fgIjzFB8/O/5Dig==}
+    peerDependencies:
+      css-tree: ^3.2.1
+    peerDependenciesMeta:
+      css-tree:
+        optional: true
+
+  '@csstools/css-tokenizer@4.0.0':
+    resolution: {integrity: sha512-QxULHAm7cNu72w97JUNCBFODFaXpbDg+dP8b/oWFAZ2MTRppA3U00Y2L1HqaS4J6yBqxwa/Y3nMBaxVKbB/NsA==}
+    engines: {node: '>=20.19.0'}
+
+  '@emnapi/core@1.11.1':
+    resolution: {integrity: sha512-RSvbQmHzdKzNsLYa/wHrbc3KN4sYLKAdPZxqiM2HATqv/SBk2/ENSHpvXGaLOMcsAyz0poEGqkmmKYG3OWiJEQ==}
+
+  '@emnapi/runtime@1.11.1':
+    resolution: {integrity: sha512-vgj7R3y3Wgx24IQaGPA/R6YFXLHVMOZ0uVEyIQPaWs+rd1AzfEMXlAC22FYwO1XkKR6NPsq7mUandH8oIRdZFw==}
+
+  '@emnapi/wasi-threads@1.2.2':
+    resolution: {integrity: sha512-c95qOXkHdydNKhscBTebqEC1CVAZpyqOfVfBzQ1qgzyl3gfeldUjIggDbIZgDKsHLgnsM+igH7TJ/eAasaVuMA==}
+
+  '@exodus/bytes@1.15.1':
+    resolution: {integrity: sha512-S6mL0yNB/Abt9Ei4tq8gDhcczc4S3+vQ4ra7vxnAf+YHC02srtqxKKZghx2Dq6p0e66THKwR6r8N6P95wEty7Q==}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+    peerDependencies:
+      '@noble/hashes': ^1.8.0 || ^2.0.0
+    peerDependenciesMeta:
+      '@noble/hashes':
+        optional: true
+
+  '@jest/types@27.0.2':
+    resolution: {integrity: sha512-XpjCtJ/99HB4PmyJ2vgmN7vT+JLP7RW1FBT9RgnMFS4Dt7cvIyBee8O3/j98aUZ34ZpenPZFqmaaObWSeL65dg==}
+    engines: {node: ^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0}
+
+  '@jridgewell/resolve-uri@3.1.2':
+    resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
+    engines: {node: '>=6.0.0'}
+
+  '@jridgewell/sourcemap-codec@1.4.14':
+    resolution: {integrity: sha512-XPSJHWmi394fuUuzDnGz1wiKqWfo1yXecHQMRf2l6hztTO+nPru658AyDngaBe7isIxEkRsPR3FZh+s7iVa4Uw==}
+
+  '@jridgewell/sourcemap-codec@1.5.5':
+    resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
+
+  '@napi-rs/wasm-runtime@1.2.0':
+    resolution: {integrity: sha512-kDoONqMa+VnZ4vvvu/ZUurpJ4gkZU57e7g69qpNgWhYcZFPUHZM2CEMKm+cG6ufDVALbjMvfmMjFVqaK7uEMnA==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=23.5.0}
+    peerDependencies:
+      '@emnapi/core': ^2.0.0-alpha.3
+      '@emnapi/runtime': ^2.0.0-alpha.3
+
+  '@oxc-project/types@0.139.0':
+    resolution: {integrity: sha512-r9gHphtCs+1M7J0pw6Sn/hh/Wpa/iQrOOkrNAlVLF/gHq+/CJmHIWKKUUhdWjcD6CIa8idarspCsASiXCXvFUw==}
+
+  '@playwright/test@1.61.1':
+    resolution: {integrity: sha512-8nKv6+0RJSL9FE4jYOEGXnPeM/Hg12qZpmqzZjRh3qM0Y7c3z1mrOTfFLids72RDQYVh9WpLEfR5WdpNX4fkig==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  '@rolldown/binding-android-arm64@1.1.5':
+    resolution: {integrity: sha512-lZg8fqIv2v7FF237bwMgzGZEJvGL79/s5knJ/i6FmsGF4XXlzccZ4jb+TrFIxtSSxFtIpdsgrPZeMk1I9AFcyQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@rolldown/binding-darwin-arm64@1.1.5':
+    resolution: {integrity: sha512-51Bnx9pNiMRKSUNtBfySkNJ9vMU9Hh3I1ozDd6gyPPYzaXCfnptUcEZxXGYFn+ul2dtcMUiqGR1Yai2K10uoTw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-x64@1.1.5':
+    resolution: {integrity: sha512-Tm+gbfC0aHu1tBA/JvKQh32S0K6YgCHkiAF4/W6xX0K0RmNuc94VeK419dJoE65R5aRxmo+noZQSWrAMF6yb6g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rolldown/binding-freebsd-x64@1.1.5':
+    resolution: {integrity: sha512-JMzDKCCXq93YccG5gz3hvOs1oXRKAf0XYpfOS88e+wZrC8Iugj6j68867vrYZkvpDDpKn/KoKORThmchMpF6TA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.1.5':
+    resolution: {integrity: sha512-uML21j2K5TfPGutKxub+M+nLjZIrWjXQ5Grx4lCe/nimTj9B4L63zHpjXLl4y0L3mcm2htEQIb06oCG/szerNw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-gnu@1.1.5':
+    resolution: {integrity: sha512-navSiuTMogvnQoZoM/v+l3ZWo50/NTwSHSzheABx/RCnmUPaKwq9qSo4Br2OYRs21+Fz8uFqITZM3H4opOB0/Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-arm64-musl@1.1.5':
+    resolution: {integrity: sha512-lAryqH7IteztmCXQXk0etKj4wBQ7Gx5S6LjKhsgp9zb8I5bsuvU/2llH1hDQcjsFeqIsovMVN339/8pUDDBXxA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-linux-ppc64-gnu@1.1.5':
+    resolution: {integrity: sha512-fsK/sNBnxzBlL4O1JNrZakVQxPspqpED5dLtNsZS9oOKmtSpdNIzxH2kkol5HYTWJN47sE20ztMJPxfZ89qGOg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-s390x-gnu@1.1.5':
+    resolution: {integrity: sha512-gLYb4BIadlfTOYT5gO503n8zQjXflgzpD0FcyKh0Mzx3rqCZKnHoJWV9xe1KXUJ5lx2JfcSHr/mhzS0PC/McAA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-gnu@1.1.5':
+    resolution: {integrity: sha512-FjcpEKUyJygHgs1o50VYNvkt5+7Le/VEdYt0AkRpkL33MnyQfwr8l5mXwMmfmTbyMPr5vJLC+8/Gd9gXnwU1QQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-musl@1.1.5':
+    resolution: {integrity: sha512-Me+PfPI2TMeOQk0gYWfLQZtTktrmzbr8cDboqX83XKc7UrgAi55gF+2dUkWdxd19n55Essp2yeca+O9N5rBxHg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-openharmony-arm64@1.1.5':
+    resolution: {integrity: sha512-yc5WrLzXks6zCQfn9Oxr8pORKyl/pF+QjHmW/Qx3qu0oyrrNC+y2JLTU1E2rcWYAmzlnqngWXHQjy51VzW70Vw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rolldown/binding-wasm32-wasi@1.1.5':
+    resolution: {integrity: sha512-VbQGPX2b4r48TAMIM2cjgluIM1HYutm4pcTEJsle7iEP7sB1dFqtPLBVbdLAZCxy1txCcPxf4QFf4v8uvltPqA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [wasm32]
+
+  '@rolldown/binding-win32-arm64-msvc@1.1.5':
+    resolution: {integrity: sha512-gHv82k63z4qpV5+Q1y/12KrK0ltWBukVDI8nZcbT7Tt/ZlOIVwppazneq0F93oDxTo3IgAMEDIoQh3E2n6mVsw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rolldown/binding-win32-x64-msvc@1.1.5':
+    resolution: {integrity: sha512-tTZuDBPw85tEN5PQi1pnEBzDy0Z49HtScLAbD5t6hyeU92A95pRWaSMw1GZZi/RwgSgUIl0xrSlXIT/9QzvYSA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@rolldown/pluginutils@1.0.1':
+    resolution: {integrity: sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==}
+
+  '@standard-schema/spec@1.1.0':
+    resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
+
+  '@testing-library/dom@10.4.1':
+    resolution: {integrity: sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==}
+    engines: {node: '>=18'}
+
+  '@testing-library/jest-dom@7.0.0':
+    resolution: {integrity: sha512-HKAH9C6mBo5yBG6yRO5i43L2iisencAo5z+o5P/saHUoY+miC5ivXRxHBJcFyB5ypPNxHJdK3BoF/3O4DIptMg==}
+    engines: {node: '>=22', npm: '>=6', yarn: '>=1'}
+    peerDependencies:
+      '@testing-library/dom': '>=10 <11'
+
+  '@testing-library/react@16.3.2':
+    resolution: {integrity: sha512-XU5/SytQM+ykqMnAnvB2umaJNIOsLF3PVv//1Ew4CTcpz0/BRyy/af40qqrt7SjKpDdT1saBMc42CUok5gaw+g==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@testing-library/dom': ^10.0.0
+      '@types/react': ^18.0.0 || ^19.0.0
+      '@types/react-dom': ^18.0.0 || ^19.0.0
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@testing-library/user-event@14.6.1':
+    resolution: {integrity: sha512-vq7fv0rnt+QTXgPxr5Hjc210p6YKq2kmdziLgnsZGgLJ9e6VAShx1pACLuRjd/AS/sr7phAR58OIIpf0LlmQNw==}
+    engines: {node: '>=12', npm: '>=6'}
+    peerDependencies:
+      '@testing-library/dom': '>=7.21.4'
+
+  '@tybys/wasm-util@0.10.3':
+    resolution: {integrity: sha512-F3fo1MYrRJYL3zER0OUOmkutjr1Vp23m7OsSgp7nq4SP6OqX6C/56XFIPAl5bt3zaBRjmW7SGz3u/6LwFpYcOg==}
+
+  '@types/aria-query@5.0.4':
+    resolution: {integrity: sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==}
+
+  '@types/chai@5.2.3':
+    resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
+
+  '@types/deep-eql@4.0.2':
+    resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
+
+  '@types/estree@1.0.9':
+    resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
+
+  '@types/istanbul-lib-coverage@2.0.6':
+    resolution: {integrity: sha512-2QF/t/auWm0lsy8XtKVPG19v3sSOQlJe/YHZgfjb/KBBHOGSV+J2q/S671rcq9uTBrLAXmZpqJiaQbMT+zNU1w==}
+
+  '@types/istanbul-lib-report@3.0.3':
+    resolution: {integrity: sha512-NQn7AHQnk/RSLOxrBbGyJM/aVQ+pjj5HCgasFxc0K/KhoATfQ/47AyUl15I2yBUpihjmas+a+VJBOqecrFH+uA==}
+
+  '@types/istanbul-reports@3.0.4':
+    resolution: {integrity: sha512-pk2B1NWalF9toCRu6gjBzR69syFjP4Od8WRAX+0mmf9lAjCRicLOWc+ZrxZHx/0XRjotgkF9t6iaMJ+aXcOdZQ==}
+
+  '@types/node@26.1.1':
+    resolution: {integrity: sha512-nxAkRSVkN1Y0JC1W8ky/fTfkGsMmcrRsbx+3XoZE+rMOX71kLYTV7fLXpqud1GpbpP5TuffXFqfX7fH2GgZREw==}
+
+  '@types/react-dom@19.2.3':
+    resolution: {integrity: sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==}
+    peerDependencies:
+      '@types/react': ^19.2.0
+
+  '@types/react@19.2.17':
+    resolution: {integrity: sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw==}
+
+  '@types/yargs-parser@21.0.3':
+    resolution: {integrity: sha512-I4q9QU9MQv4oEOz4tAHJtNz1cwuLxn2F3xcc2iV5WdqLPpUnj30aUuxt1mAxYTG+oe8CZMV/+6rU4S4gRDzqtQ==}
+
+  '@types/yargs@16.0.11':
+    resolution: {integrity: sha512-sbtvk8wDN+JvEdabmZExoW/HNr1cB7D/j4LT08rMiuikfA7m/JNJg7ATQcgzs34zHnoScDkY0ZRSl29Fkmk36g==}
+
+  '@typescript/typescript-aix-ppc64@7.0.2':
+    resolution: {integrity: sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@typescript/typescript-darwin-arm64@7.0.2':
+    resolution: {integrity: sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@typescript/typescript-darwin-x64@7.0.2':
+    resolution: {integrity: sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@typescript/typescript-freebsd-arm64@7.0.2':
+    resolution: {integrity: sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@typescript/typescript-freebsd-x64@7.0.2':
+    resolution: {integrity: sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@typescript/typescript-linux-arm64@7.0.2':
+    resolution: {integrity: sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@typescript/typescript-linux-arm@7.0.2':
+    resolution: {integrity: sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm]
+    os: [linux]
+
+  '@typescript/typescript-linux-loong64@7.0.2':
+    resolution: {integrity: sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@typescript/typescript-linux-mips64el@7.0.2':
+    resolution: {integrity: sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@typescript/typescript-linux-ppc64@7.0.2':
+    resolution: {integrity: sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@typescript/typescript-linux-riscv64@7.0.2':
+    resolution: {integrity: sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@typescript/typescript-linux-s390x@7.0.2':
+    resolution: {integrity: sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw==}
+    engines: {node: '>=16.20.0'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@typescript/typescript-linux-x64@7.0.2':
+    resolution: {integrity: sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [linux]
+
+  '@typescript/typescript-netbsd-arm64@7.0.2':
+    resolution: {integrity: sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@typescript/typescript-netbsd-x64@7.0.2':
+    resolution: {integrity: sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@typescript/typescript-openbsd-arm64@7.0.2':
+    resolution: {integrity: sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@typescript/typescript-openbsd-x64@7.0.2':
+    resolution: {integrity: sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@typescript/typescript-sunos-x64@7.0.2':
+    resolution: {integrity: sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@typescript/typescript-win32-arm64@7.0.2':
+    resolution: {integrity: sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@typescript/typescript-win32-x64@7.0.2':
+    resolution: {integrity: sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [win32]
+
+  '@vitejs/plugin-react@6.0.3':
+    resolution: {integrity: sha512-vmFvco5/QuC2f9Oj+wTk0+9XeDFkHxSamwZKYc7MxYwKICfvUvlMhqKI0VuICPltGqh1neqBKDvO4kes1ya8vg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      '@rolldown/plugin-babel': ^0.1.7 || ^0.2.0
+      babel-plugin-react-compiler: ^1.0.0
+      vite: ^8.0.0
+    peerDependenciesMeta:
+      '@rolldown/plugin-babel':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+
+  '@vitest/coverage-v8@4.1.10':
+    resolution: {integrity: sha512-IM49HmthevbgAO4anp1hwtoT9wYe59w0LR00gr+eagHE+ZJ5lK4sLPeO0ubgoJcwLk6dehU3R24N+FbEEKDc8g==}
+    peerDependencies:
+      '@vitest/browser': 4.1.10
+      vitest: 4.1.10
+    peerDependenciesMeta:
+      '@vitest/browser':
+        optional: true
+
+  '@vitest/expect@4.1.10':
+    resolution: {integrity: sha512-YsCn+qAk1GWjQOWFEsEcL2gNQ0zmVmQu3T03qP6UyjhtmdtwtbuI+DASn/7iQB3HGTXkdBwGddzxPlmiql5vlA==}
+
+  '@vitest/mocker@4.1.10':
+    resolution: {integrity: sha512-v0xaezt+DKEmKfaxg133ldzADrwLGd7Ze1MfQQTYfvs8OqZIwbxyxaYURivwV7sWy5fqn3rH5uOrSp07bp44Ow==}
+    peerDependencies:
+      msw: ^2.4.9
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      msw:
+        optional: true
+      vite:
+        optional: true
+
+  '@vitest/pretty-format@4.1.10':
+    resolution: {integrity: sha512-W1HsjSH4MXQ9YfmmhLAoIYf1HRfekQCGngeIgcei6MP5QQGWUe0gkopdZQaVCFO+JDJMrAJGwa5pRpNpvy4P8Q==}
+
+  '@vitest/runner@4.1.10':
+    resolution: {integrity: sha512-IKI6kpIH+LmpROplyLwBBaCfMgOZOMsygVa6BARD6ahA04VRuJSa6OaVG7kRvSEMD870Vd91rSSw0eegtWyLGg==}
+
+  '@vitest/snapshot@4.1.10':
+    resolution: {integrity: sha512-xRkfOT1qpTAi/Ti4Y1LtfRc3kEuqxGw59eN2jN9pRWMtS/XDevekhcFSqvQqjUNGksfjMJu3Y+oJ+4Ypn2OaJw==}
+
+  '@vitest/spy@4.1.10':
+    resolution: {integrity: sha512-PLf/Ugvoq5wO/b4rwYCR1h2PSIdXz7wnkQFMiUpLdtM7l6pqVFcQIBEHyT1+l+cj7mNwAfZHzqXqDyjvOuwbDw==}
+
+  '@vitest/utils@4.1.10':
+    resolution: {integrity: sha512-fy9am/HWxbaGt/Sawrp90vt6Y6jQwf1RX77cz3uwoJwJVMli/e1IEwRPnMNJ7vKfPTwo0diXifkpPvwH9v7nGA==}
+
+  '@wailsio/runtime@3.0.0-alpha2.117':
+    resolution: {integrity: sha512-RZr6cncIXjdTbn2IqJ6AZXPm9WooaZEsNlNfaUH+Ru/YlH5sKDDeRdWpbcvsgoMLh4AJ+O8aBzZEiTYWDipGxw==}
+
+  ansi-regex@5.0.1:
+    resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
+    engines: {node: '>=8'}
+
+  ansi-styles@4.1.0:
+    resolution: {integrity: sha512-Qts4KCLKG+waHc9C4m07weIY8qyeixoS0h6RnbsNVD6Fw+pEZGW3vTyObL3WXpE09Mq4Oi7/lBEyLmOiLtlYWQ==}
+    engines: {node: '>=8'}
+
+  ansi-styles@5.0.0:
+    resolution: {integrity: sha512-6564t0m0fuQMnockqBv7wJxo9T5C2V9JpYXyNScfRDPVLusOQQhkpMGrFC17QbiolraQ1sMXX+Y5nJpjqozL4g==}
+    engines: {node: '>=10'}
+
+  aria-query@5.3.0:
+    resolution: {integrity: sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==}
+
+  aria-query@5.3.2:
+    resolution: {integrity: sha512-COROpnaoap1E2F000S62r6A60uHZnmlvomhfyT2DlTcrY1OrBKn2UhH7qn5wTC9zMvD0AY7csdPSNwKP+7WiQw==}
+    engines: {node: '>= 0.4'}
+
+  assertion-error@2.0.1:
+    resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
+    engines: {node: '>=12'}
+
+  ast-v8-to-istanbul@1.0.5:
+    resolution: {integrity: sha512-UPAgKJFSEGMWSDr3LX4tqnAb4f7KGT8O40Tyx8wbYmmZ/yn58lNCm8h3svs3eXgiGd5AXxz8NDOvXWvicq+rJA==}
+
+  bidi-js@1.0.3:
+    resolution: {integrity: sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==}
+
+  chai@6.2.2:
+    resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
+    engines: {node: '>=18'}
+
+  chalk@4.0.0:
+    resolution: {integrity: sha512-N9oWFcegS0sFr9oh1oz2d7Npos6vNoWW9HvtCg5N1KRFpUhaAhvTv5Y58g880fZaEYSNm3qDz8SU1UrGvp+n7A==}
+    engines: {node: '>=10'}
+
+  color-convert@2.0.1:
+    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
+    engines: {node: '>=7.0.0'}
+
+  color-name@1.1.4:
+    resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
+
+  convert-source-map@2.0.0:
+    resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
+
+  cookie@1.0.1:
+    resolution: {integrity: sha512-Xd8lFX4LM9QEEwxQpF9J9NTUh8pmdJO0cyRJhFiDoLTk2eH8FXlRv2IFGYVadZpqI3j8fhNrSdKCeYPxiAhLXw==}
+    engines: {node: '>=18'}
+
+  css-tree@3.2.1:
+    resolution: {integrity: sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA==}
+    engines: {node: ^10 || ^12.20.0 || ^14.13.0 || >=15.0.0}
+
+  css.escape@1.5.1:
+    resolution: {integrity: sha512-YUifsXXuknHlUsmlgyY0PKzgPOr7/FjCePfHNt0jxm83wHZi44VDMQ7/fGNkjY3/jV1MC+1CmZbaHzugyeRtpg==}
+
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
+
+  data-urls@7.0.0:
+    resolution: {integrity: sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA==}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  decimal.js@10.6.0:
+    resolution: {integrity: sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==}
+
+  dequal@2.0.3:
+    resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
+    engines: {node: '>=6'}
+
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
+  dom-accessibility-api@0.5.16:
+    resolution: {integrity: sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==}
+
+  dom-accessibility-api@0.6.3:
+    resolution: {integrity: sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w==}
+
+  entities@8.0.0:
+    resolution: {integrity: sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA==}
+    engines: {node: '>=20.19.0'}
+
+  es-module-lexer@2.3.1:
+    resolution: {integrity: sha512-shc1dbU90Yl/xq1QrC7QRtfcwURZuVRfPhZbDoldJ1cn1gzDvBaBWlv0eFolj5+0znnPJz5TXLxsN77X/12KTA==}
+
+  estree-walker@3.0.3:
+    resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
+
+  expect-type@1.4.0:
+    resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
+    engines: {node: '>=12.0.0'}
+
+  fdir@6.5.0:
+    resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
+    engines: {node: '>=12.0.0'}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  fsevents@2.3.2:
+    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  has-flag@4.0.0:
+    resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
+    engines: {node: '>=8'}
+
+  html-encoding-sniffer@6.0.0:
+    resolution: {integrity: sha512-CV9TW3Y3f8/wT0BRFc1/KAVQ3TUHiXmaAb6VW9vtiMFf7SLoMd1PdAc4W3KFOFETBJUb90KatHqlsZMWV+R9Gg==}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  html-escaper@2.0.2:
+    resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==}
+
+  indent-string@4.0.0:
+    resolution: {integrity: sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==}
+    engines: {node: '>=8'}
+
+  is-potential-custom-element-name@1.0.1:
+    resolution: {integrity: sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==}
+
+  istanbul-lib-coverage@3.2.2:
+    resolution: {integrity: sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==}
+    engines: {node: '>=8'}
+
+  istanbul-lib-report@3.0.1:
+    resolution: {integrity: sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==}
+    engines: {node: '>=10'}
+
+  istanbul-reports@3.2.0:
+    resolution: {integrity: sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==}
+    engines: {node: '>=8'}
+
+  js-tokens@10.0.0:
+    resolution: {integrity: sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==}
+
+  js-tokens@4.0.0:
+    resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
+
+  jsdom@29.1.1:
+    resolution: {integrity: sha512-ECi4Fi2f7BdJtUKTflYRTiaMxIB0O6zfR1fX0GXpUrf6flp8QIYn1UT20YQqdSOfk2dfkCwS8LAFoJDEppNK5Q==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24.0.0}
+    peerDependencies:
+      canvas: ^3.0.0
+    peerDependenciesMeta:
+      canvas:
+        optional: true
+
+  lightningcss-android-arm64@1.33.0:
+    resolution: {integrity: sha512-gEpRTalKdosp4Bb8qWtc2iOgE5SeIHlpS1up9bFq2wAyYhl1UdTObYiHe98zEM9SQvSoqQZ1IQD0JNpg3Ml5pg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.33.0:
+    resolution: {integrity: sha512-Sciaz8eenNTKn9b3t7+xr0ipTp9YxKQY4npwQ3mrRuL0BAVHBLyZxofhaKBAVtzmtRZ/zTyo0/to4B1uWG/Djg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.33.0:
+    resolution: {integrity: sha512-Z5UPAxzrjlWNNyGy6i65cJzzvgJ5D3T6wMvs+gWpY9d7qRhANrxqAp6LhxIgZhWEw18RfJTGcRxjuLIBr+m8XQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.33.0:
+    resolution: {integrity: sha512-QQM/Ti/hQajJwCY+RiWuCZ9sdtI/XQk7nDK5vC8kkdwixezOlDgvDx7+RT+QjK6FcFT4MpsuoBnHIo/O3StRRg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.33.0:
+    resolution: {integrity: sha512-N7FVBe6iS24MlM6R/4RBTxGhQheZGs7tiQ9U32UtF75NzP5Q7xWPRqLBCKxlRQRk3rY1jCIPLzx7WzOhuUIRLQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.33.0:
+    resolution: {integrity: sha512-j2v/itmy4HlNxlc6voKXYgBqNi0Ng2LShg4z7GufpEgs05P+2suBVyi9I6YHq5uoVFx9ETin3eCEhLVyXGQnKg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-arm64-musl@1.33.0:
+    resolution: {integrity: sha512-yiO5ROMuYQgXbC60yjZU5CYSFZGKXL0HFATXt9mHJn1+zW55oCtMI9NfcVhYLMFDL7gV7oBPon/EmMMGg2OvtQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-linux-x64-gnu@1.33.0:
+    resolution: {integrity: sha512-ar+Ju7LmcN0Jo4FpL4hpFybwNG9/3A/Br5KW2n2jyODg3MEZXaDYADdemoNS+BDNfMgKvylJLj4S5tyRActuAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-x64-musl@1.33.0:
+    resolution: {integrity: sha512-RYiYbkokw0trfKqqzfF55lginwEPrD3OJDfTuJzFs1MK6iFnDenaz1fqLLtX4ITG3OktJQXOeTaw1awrBAlZPw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-win32-arm64-msvc@1.33.0:
+    resolution: {integrity: sha512-1K+MPfLSFVpphzpdbfkhlWk6wBrTObBzS2T6db10PNOZgR9GoVsAWzwNyuhUYYbTp23j+4RrncfujZ4uAzXvwA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.33.0:
+    resolution: {integrity: sha512-OlEICDx/Xl0FqSp4bry8zFnCvGpig3Gl4gCquvYwHuqJKEC1+n9NgDniFvqHGmMv1ZkqDJrDqKKSykTDX+ehuA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.33.0:
+    resolution: {integrity: sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA==}
+    engines: {node: '>= 12.0.0'}
+
+  lru-cache@11.5.2:
+    resolution: {integrity: sha512-4pfM1Ff0x50o0tQwb5ucw/RzNyD0/YJME6IVcStalZuMWxdt3sR3huStTtxz4PUmvZfRguvDejasvQ2kifR11g==}
+    engines: {node: 20 || >=22}
+
+  lucide-react@1.25.0:
+    resolution: {integrity: sha512-/mdJTRbiwcLOQ1NZZK1amZF9rIZyvO18D6r9TngE6TG1NmqHgFuT4eE7Xrkm9UsXMbBJD1NlfwHVltCDWHrOTw==}
+    peerDependencies:
+      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  lz-string@1.5.0:
+    resolution: {integrity: sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==}
+    hasBin: true
+
+  magic-string@0.30.21:
+    resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
+
+  magicast@0.5.3:
+    resolution: {integrity: sha512-pVKE4UdSQ7DvHzivsCIFx2BJn1mHG6KsyrFcaxFx6tONdneEuThrDx0Cj3AMg58KyN4pzYT+LHOotxDQDjNvkw==}
+
+  make-dir@4.0.0:
+    resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==}
+    engines: {node: '>=10'}
+
+  mdn-data@2.27.1:
+    resolution: {integrity: sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ==}
+
+  min-indent@1.0.1:
+    resolution: {integrity: sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg==}
+    engines: {node: '>=4'}
+
+  nanoid@3.3.16:
+    resolution: {integrity: sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  obug@2.1.4:
+    resolution: {integrity: sha512-4a+OsYv9UktOJKE+l1A4OufDgdRF9PifWj+tJnHURo/P+WOxpG4GzUFL9qCalmWauao6ogiG+QvnCovwPoyAWA==}
+    engines: {node: '>=12.20.0'}
+
+  parse5@8.0.1:
+    resolution: {integrity: sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==}
+
+  pathe@2.0.3:
+    resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  picomatch@4.0.5:
+    resolution: {integrity: sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==}
+    engines: {node: '>=12'}
+
+  playwright-core@1.61.1:
+    resolution: {integrity: sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  playwright@1.61.1:
+    resolution: {integrity: sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  postcss@8.5.24:
+    resolution: {integrity: sha512-8RyVklq0owXUTa4xlpzu4l9AaVKIdQvAcOHZWaMh98HgySsUtxRVf/chRe3dsSLqb6i40BzGRzEUddRaI+9TSw==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  pretty-format@27.0.2:
+    resolution: {integrity: sha512-mXKbbBPnYTG7Yra9qFBtqj+IXcsvxsvOBco3QHxtxTl+hHKq6QdzMZ+q0CtL4ORHZgwGImRr2XZUX2EWzORxig==}
+    engines: {node: ^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0}
+
+  punycode@2.3.1:
+    resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
+    engines: {node: '>=6'}
+
+  react-dom@19.2.8:
+    resolution: {integrity: sha512-rVprimfGBG3DR+Tq0IQG2DT5PxKth1WIGDmj5yPmlzr4YBe7uyE+Du4oVqTDXZSHGGGXRtTJEGSSePyQCMBglQ==}
+    peerDependencies:
+      react: ^19.2.8
+
+  react-is@17.0.1:
+    resolution: {integrity: sha512-NAnt2iGDXohE5LI7uBnLnqvLQMtzhkiAOLXTmv+qnF9Ky7xAPcX8Up/xWIhxvLVGJvuLiNc4xQLtuqDRzb4fSA==}
+
+  react-router-dom@7.18.1:
+    resolution: {integrity: sha512-KaZh+X/6UtEp28x51AUYZDMg9NGoz2ja3dNHa+ta/tk40vCzKhQ/RypCWBMLbmDr6//E24Vv5uPsrqXFozdkAg==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+
+  react-router@7.18.1:
+    resolution: {integrity: sha512-GDLgg3i3uM0aeJO3Fm+TCS+sDQ7gu12T6x0qdTEzcwqEfleci7JwugVNIF3U//0FWKnJT7ptG+20B2jfDqnZAg==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+
+  react@19.2.8:
+    resolution: {integrity: sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==}
+    engines: {node: '>=0.10.0'}
+
+  redent@3.0.0:
+    resolution: {integrity: sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==}
+    engines: {node: '>=8'}
+
+  require-from-string@2.0.2:
+    resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
+    engines: {node: '>=0.10.0'}
+
+  rolldown@1.1.5:
+    resolution: {integrity: sha512-t9z29cJjXf/vxQ8dyhCSpt6H6aSwHTk8cT5I3iy6SMXuFpk5mB6PL6XfC8PCwrPTx93udwKUm9HRteAlTGBLiA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
+  saxes@6.0.0:
+    resolution: {integrity: sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==}
+    engines: {node: '>=v12.22.7'}
+
+  scheduler@0.27.0:
+    resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
+
+  semver@7.8.5:
+    resolution: {integrity: sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==}
+    engines: {node: '>=10'}
+    hasBin: true
+
+  set-cookie-parser@2.6.0:
+    resolution: {integrity: sha512-RVnVQxTXuerk653XfuliOxBP81Sf0+qfQE73LIYKcyMYHG94AuH0kgrQpRDuTZnSmjpysHmzxJXKNfa6PjFhyQ==}
+
+  siginfo@2.0.0:
+    resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
+
+  source-map-js@1.2.1:
+    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
+    engines: {node: '>=0.10.0'}
+
+  stackback@0.0.2:
+    resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
+
+  std-env@4.2.0:
+    resolution: {integrity: sha512-oCUKSupKTHX53EyjDtuZQ64pjLJ6yYCtpmEw0goYxtjG9KpbRe8KAsl2tBUGU9DyMcJ0RwJ8GqJAFzMXcXW1Rw==}
+
+  strip-indent@3.0.0:
+    resolution: {integrity: sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==}
+    engines: {node: '>=8'}
+
+  supports-color@7.1.0:
+    resolution: {integrity: sha512-oRSIpR8pxT1Wr2FquTNnGet79b3BWljqOuoW/h4oBhxJ/HUbX5nX6JSruTkvXDCFMwDPvsaTTbvMLKZWSy0R5g==}
+    engines: {node: '>=8'}
+
+  symbol-tree@3.2.4:
+    resolution: {integrity: sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==}
+
+  tinybench@2.9.0:
+    resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
+
+  tinyexec@1.2.4:
+    resolution: {integrity: sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg==}
+    engines: {node: '>=18'}
+
+  tinyglobby@0.2.17:
+    resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==}
+    engines: {node: '>=12.0.0'}
+
+  tinyrainbow@3.1.1:
+    resolution: {integrity: sha512-yau8yJdTt989Mm0Bd/236QnzEiPf2xLLTqUZRUJOo/3CB078LSwzei343DgtJVmfJKJE3TMINY1u42SQsP6mXw==}
+    engines: {node: '>=14.0.0'}
+
+  tldts-core@7.4.9:
+    resolution: {integrity: sha512-DxKfPBI52p2msTEu7MPhdpdDTBhhVQg1a/8PjQckeyAvO13eMYElX545grIp6nnTGIMZlRvFZPvFhvI/WIz2Vg==}
+
+  tldts@7.4.9:
+    resolution: {integrity: sha512-3kZ8wQQ/k5DrChD4X4FVvr2D7E5uoRgAqkPyLpSCGUvqOvqu+JEdr3mwMUaVWb+vMHZaKhF5fp2PBigKsui7hA==}
+    hasBin: true
+
+  tough-cookie@6.0.2:
+    resolution: {integrity: sha512-exgYmnmL/sJpR3upZfXG5PoatXQii55xAiXGXzY+sROLZ/Y+SLcp9PgJNI9Vz37HpQ74WvDcLT8eqm+kV3FzrA==}
+    engines: {node: '>=16'}
+
+  tr46@6.0.0:
+    resolution: {integrity: sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==}
+    engines: {node: '>=20'}
+
+  tslib@2.8.1:
+    resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
+
+  typescript@7.0.2:
+    resolution: {integrity: sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA==}
+    engines: {node: '>=16.20.0'}
+    hasBin: true
+
+  undici-types@8.3.0:
+    resolution: {integrity: sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==}
+
+  undici@7.29.0:
+    resolution: {integrity: sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw==}
+    engines: {node: '>=20.18.1'}
+
+  vite@8.1.5:
+    resolution: {integrity: sha512-7ULLwsCdYx/nRyrpiEwvqb5TFHrMVZyBt+rg/OAXT7rgj/z+DtTDyKFeLAdDkubDVDKD8jOsndmy7m55XcfUsw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^20.19.0 || >=22.12.0
+      '@vitejs/devtools': ^0.3.0
+      esbuild: ^0.27.0 || ^0.28.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      '@vitejs/devtools':
+        optional: true
+      esbuild:
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+  vitest@4.1.10:
+    resolution: {integrity: sha512-R9jUTe5S4Qb0HCd4TNqpC7oGcrMssMRGXLW80ubjWsW9VH5GF8y1Y0SFLY9AbqSk6nt0PnOx4H4WNJYZ13GUPw==}
+    engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0}
+    hasBin: true
+    peerDependencies:
+      '@edge-runtime/vm': '*'
+      '@opentelemetry/api': ^1.9.0
+      '@types/node': ^20.0.0 || ^22.0.0 || >=24.0.0
+      '@vitest/browser-playwright': 4.1.10
+      '@vitest/browser-preview': 4.1.10
+      '@vitest/browser-webdriverio': 4.1.10
+      '@vitest/coverage-istanbul': 4.1.10
+      '@vitest/coverage-v8': 4.1.10
+      '@vitest/ui': 4.1.10
+      happy-dom: '*'
+      jsdom: '*'
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      '@edge-runtime/vm':
+        optional: true
+      '@opentelemetry/api':
+        optional: true
+      '@types/node':
+        optional: true
+      '@vitest/browser-playwright':
+        optional: true
+      '@vitest/browser-preview':
+        optional: true
+      '@vitest/browser-webdriverio':
+        optional: true
+      '@vitest/coverage-istanbul':
+        optional: true
+      '@vitest/coverage-v8':
+        optional: true
+      '@vitest/ui':
+        optional: true
+      happy-dom:
+        optional: true
+      jsdom:
+        optional: true
+
+  w3c-xmlserializer@5.0.0:
+    resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==}
+    engines: {node: '>=18'}
+
+  webidl-conversions@8.0.1:
+    resolution: {integrity: sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==}
+    engines: {node: '>=20'}
+
+  whatwg-mimetype@5.0.0:
+    resolution: {integrity: sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw==}
+    engines: {node: '>=20'}
+
+  whatwg-url@16.0.1:
+    resolution: {integrity: sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw==}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
+
+  why-is-node-running@2.3.0:
+    resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==}
+    engines: {node: '>=8'}
+    hasBin: true
+
+  xml-name-validator@5.0.0:
+    resolution: {integrity: sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==}
+    engines: {node: '>=18'}
+
+  xmlchars@2.2.0:
+    resolution: {integrity: sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==}
+
+snapshots:
+
+  '@adobe/css-tools@4.5.0': {}
+
+  '@asamuzakjp/css-color@5.1.11':
+    dependencies:
+      '@asamuzakjp/generational-cache': 1.0.1
+      '@csstools/css-calc': 3.3.0(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-color-parser': 4.1.10(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-tokenizer': 4.0.0
+
+  '@asamuzakjp/dom-selector@7.1.1':
+    dependencies:
+      '@asamuzakjp/generational-cache': 1.0.1
+      '@asamuzakjp/nwsapi': 2.3.9
+      bidi-js: 1.0.3
+      css-tree: 3.2.1
+      is-potential-custom-element-name: 1.0.1
+
+  '@asamuzakjp/generational-cache@1.0.1': {}
+
+  '@asamuzakjp/nwsapi@2.3.9': {}
+
+  '@babel/code-frame@7.29.7':
+    dependencies:
+      '@babel/helper-validator-identifier': 7.29.7
+      js-tokens: 4.0.0
+      picocolors: 1.1.1
+
+  '@babel/helper-string-parser@7.29.7': {}
+
+  '@babel/helper-validator-identifier@7.29.7': {}
+
+  '@babel/parser@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@babel/runtime@7.29.7': {}
+
+  '@babel/types@7.29.7':
+    dependencies:
+      '@babel/helper-string-parser': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+
+  '@bcoe/v8-coverage@1.0.2': {}
+
+  '@bramus/specificity@2.4.2':
+    dependencies:
+      css-tree: 3.2.1
+
+  '@csstools/color-helpers@6.1.0': {}
+
+  '@csstools/css-calc@3.3.0(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)':
+    dependencies:
+      '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-tokenizer': 4.0.0
+
+  '@csstools/css-color-parser@4.1.10(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)':
+    dependencies:
+      '@csstools/color-helpers': 6.1.0
+      '@csstools/css-calc': 3.3.0(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
+      '@csstools/css-tokenizer': 4.0.0
+
+  '@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0)':
+    dependencies:
+      '@csstools/css-tokenizer': 4.0.0
+
+  '@csstools/css-syntax-patches-for-csstree@1.1.7(css-tree@3.2.1)':
+    optionalDependencies:
+      css-tree: 3.2.1
+
+  '@csstools/css-tokenizer@4.0.0': {}
+
+  '@emnapi/core@1.11.1':
+    dependencies:
+      '@emnapi/wasi-threads': 1.2.2
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/runtime@1.11.1':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/wasi-threads@1.2.2':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@exodus/bytes@1.15.1': {}
+
+  '@jest/types@27.0.2':
+    dependencies:
+      '@types/istanbul-lib-coverage': 2.0.6
+      '@types/istanbul-reports': 3.0.4
+      '@types/node': 26.1.1
+      '@types/yargs': 16.0.11
+      chalk: 4.0.0
+
+  '@jridgewell/resolve-uri@3.1.2': {}
+
+  '@jridgewell/sourcemap-codec@1.4.14': {}
+
+  '@jridgewell/sourcemap-codec@1.5.5': {}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    dependencies:
+      '@jridgewell/resolve-uri': 3.1.2
+      '@jridgewell/sourcemap-codec': 1.4.14
+
+  '@napi-rs/wasm-runtime@1.2.0(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
+    dependencies:
+      '@emnapi/core': 1.11.1
+      '@emnapi/runtime': 1.11.1
+      '@tybys/wasm-util': 0.10.3
+    optional: true
+
+  '@oxc-project/types@0.139.0': {}
+
+  '@playwright/test@1.61.1':
+    dependencies:
+      playwright: 1.61.1
+
+  '@rolldown/binding-android-arm64@1.1.5':
+    optional: true
+
+  '@rolldown/binding-darwin-arm64@1.1.5':
+    optional: true
+
+  '@rolldown/binding-darwin-x64@1.1.5':
+    optional: true
+
+  '@rolldown/binding-freebsd-x64@1.1.5':
+    optional: true
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.1.5':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-gnu@1.1.5':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-musl@1.1.5':
+    optional: true
+
+  '@rolldown/binding-linux-ppc64-gnu@1.1.5':
+    optional: true
+
+  '@rolldown/binding-linux-s390x-gnu@1.1.5':
+    optional: true
+
+  '@rolldown/binding-linux-x64-gnu@1.1.5':
+    optional: true
+
+  '@rolldown/binding-linux-x64-musl@1.1.5':
+    optional: true
+
+  '@rolldown/binding-openharmony-arm64@1.1.5':
+    optional: true
+
+  '@rolldown/binding-wasm32-wasi@1.1.5':
+    dependencies:
+      '@emnapi/core': 1.11.1
+      '@emnapi/runtime': 1.11.1
+      '@napi-rs/wasm-runtime': 1.2.0(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)
+    optional: true
+
+  '@rolldown/binding-win32-arm64-msvc@1.1.5':
+    optional: true
+
+  '@rolldown/binding-win32-x64-msvc@1.1.5':
+    optional: true
+
+  '@rolldown/pluginutils@1.0.1': {}
+
+  '@standard-schema/spec@1.1.0': {}
+
+  '@testing-library/dom@10.4.1':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/runtime': 7.29.7
+      '@types/aria-query': 5.0.4
+      aria-query: 5.3.0
+      dom-accessibility-api: 0.5.16
+      lz-string: 1.5.0
+      picocolors: 1.1.1
+      pretty-format: 27.0.2
+
+  '@testing-library/jest-dom@7.0.0(@testing-library/dom@10.4.1)':
+    dependencies:
+      '@adobe/css-tools': 4.5.0
+      '@testing-library/dom': 10.4.1
+      aria-query: 5.3.2
+      css.escape: 1.5.1
+      dom-accessibility-api: 0.6.3
+      picocolors: 1.1.1
+      redent: 3.0.0
+
+  '@testing-library/react@16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@testing-library/dom': 10.4.1
+      react: 19.2.8
+      react-dom: 19.2.8(react@19.2.8)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@testing-library/user-event@14.6.1(@testing-library/dom@10.4.1)':
+    dependencies:
+      '@testing-library/dom': 10.4.1
+
+  '@tybys/wasm-util@0.10.3':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@types/aria-query@5.0.4': {}
+
+  '@types/chai@5.2.3':
+    dependencies:
+      '@types/deep-eql': 4.0.2
+      assertion-error: 2.0.1
+
+  '@types/deep-eql@4.0.2': {}
+
+  '@types/estree@1.0.9': {}
+
+  '@types/istanbul-lib-coverage@2.0.6': {}
+
+  '@types/istanbul-lib-report@3.0.3':
+    dependencies:
+      '@types/istanbul-lib-coverage': 2.0.6
+
+  '@types/istanbul-reports@3.0.4':
+    dependencies:
+      '@types/istanbul-lib-report': 3.0.3
+
+  '@types/node@26.1.1':
+    dependencies:
+      undici-types: 8.3.0
+
+  '@types/react-dom@19.2.3(@types/react@19.2.17)':
+    dependencies:
+      '@types/react': 19.2.17
+
+  '@types/react@19.2.17':
+    dependencies:
+      csstype: 3.2.3
+
+  '@types/yargs-parser@21.0.3': {}
+
+  '@types/yargs@16.0.11':
+    dependencies:
+      '@types/yargs-parser': 21.0.3
+
+  '@typescript/typescript-aix-ppc64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-darwin-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-darwin-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-freebsd-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-freebsd-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-arm@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-loong64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-mips64el@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-ppc64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-riscv64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-s390x@7.0.2':
+    optional: true
+
+  '@typescript/typescript-linux-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-netbsd-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-netbsd-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-openbsd-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-openbsd-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-sunos-x64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-win32-arm64@7.0.2':
+    optional: true
+
+  '@typescript/typescript-win32-x64@7.0.2':
+    optional: true
+
+  '@vitejs/plugin-react@6.0.3(vite@8.1.5(@types/node@26.1.1))':
+    dependencies:
+      '@rolldown/pluginutils': 1.0.1
+      vite: 8.1.5(@types/node@26.1.1)
+
+  '@vitest/coverage-v8@4.1.10(vitest@4.1.10)':
+    dependencies:
+      '@bcoe/v8-coverage': 1.0.2
+      '@vitest/utils': 4.1.10
+      ast-v8-to-istanbul: 1.0.5
+      istanbul-lib-coverage: 3.2.2
+      istanbul-lib-report: 3.0.1
+      istanbul-reports: 3.2.0
+      magicast: 0.5.3
+      obug: 2.1.4
+      std-env: 4.2.0
+      tinyrainbow: 3.1.1
+      vitest: 4.1.10(@types/node@26.1.1)(@vitest/coverage-v8@4.1.10)(jsdom@29.1.1)(vite@8.1.5(@types/node@26.1.1))
+
+  '@vitest/expect@4.1.10':
+    dependencies:
+      '@standard-schema/spec': 1.1.0
+      '@types/chai': 5.2.3
+      '@vitest/spy': 4.1.10
+      '@vitest/utils': 4.1.10
+      chai: 6.2.2
+      tinyrainbow: 3.1.1
+
+  '@vitest/mocker@4.1.10(vite@8.1.5(@types/node@26.1.1))':
+    dependencies:
+      '@vitest/spy': 4.1.10
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 8.1.5(@types/node@26.1.1)
+
+  '@vitest/pretty-format@4.1.10':
+    dependencies:
+      tinyrainbow: 3.1.1
+
+  '@vitest/runner@4.1.10':
+    dependencies:
+      '@vitest/utils': 4.1.10
+      pathe: 2.0.3
+
+  '@vitest/snapshot@4.1.10':
+    dependencies:
+      '@vitest/pretty-format': 4.1.10
+      '@vitest/utils': 4.1.10
+      magic-string: 0.30.21
+      pathe: 2.0.3
+
+  '@vitest/spy@4.1.10': {}
+
+  '@vitest/utils@4.1.10':
+    dependencies:
+      '@vitest/pretty-format': 4.1.10
+      convert-source-map: 2.0.0
+      tinyrainbow: 3.1.1
+
+  '@wailsio/runtime@3.0.0-alpha2.117': {}
+
+  ansi-regex@5.0.1: {}
+
+  ansi-styles@4.1.0:
+    dependencies:
+      color-convert: 2.0.1
+
+  ansi-styles@5.0.0: {}
+
+  aria-query@5.3.0:
+    dependencies:
+      dequal: 2.0.3
+
+  aria-query@5.3.2: {}
+
+  assertion-error@2.0.1: {}
+
+  ast-v8-to-istanbul@1.0.5:
+    dependencies:
+      '@jridgewell/trace-mapping': 0.3.31
+      estree-walker: 3.0.3
+      js-tokens: 10.0.0
+
+  bidi-js@1.0.3:
+    dependencies:
+      require-from-string: 2.0.2
+
+  chai@6.2.2: {}
+
+  chalk@4.0.0:
+    dependencies:
+      ansi-styles: 4.1.0
+      supports-color: 7.1.0
+
+  color-convert@2.0.1:
+    dependencies:
+      color-name: 1.1.4
+
+  color-name@1.1.4: {}
+
+  convert-source-map@2.0.0: {}
+
+  cookie@1.0.1: {}
+
+  css-tree@3.2.1:
+    dependencies:
+      mdn-data: 2.27.1
+      source-map-js: 1.2.1
+
+  css.escape@1.5.1: {}
+
+  csstype@3.2.3: {}
+
+  data-urls@7.0.0:
+    dependencies:
+      whatwg-mimetype: 5.0.0
+      whatwg-url: 16.0.1
+    transitivePeerDependencies:
+      - '@noble/hashes'
+
+  decimal.js@10.6.0: {}
+
+  dequal@2.0.3: {}
+
+  detect-libc@2.1.2: {}
+
+  dom-accessibility-api@0.5.16: {}
+
+  dom-accessibility-api@0.6.3: {}
+
+  entities@8.0.0: {}
+
+  es-module-lexer@2.3.1: {}
+
+  estree-walker@3.0.3:
+    dependencies:
+      '@types/estree': 1.0.9
+
+  expect-type@1.4.0: {}
+
+  fdir@6.5.0(picomatch@4.0.5):
+    optionalDependencies:
+      picomatch: 4.0.5
+
+  fsevents@2.3.2:
+    optional: true
+
+  fsevents@2.3.3:
+    optional: true
+
+  has-flag@4.0.0: {}
+
+  html-encoding-sniffer@6.0.0:
+    dependencies:
+      '@exodus/bytes': 1.15.1
+    transitivePeerDependencies:
+      - '@noble/hashes'
+
+  html-escaper@2.0.2: {}
+
+  indent-string@4.0.0: {}
+
+  is-potential-custom-element-name@1.0.1: {}
+
+  istanbul-lib-coverage@3.2.2: {}
+
+  istanbul-lib-report@3.0.1:
+    dependencies:
+      istanbul-lib-coverage: 3.2.2
+      make-dir: 4.0.0
+      supports-color: 7.1.0
+
+  istanbul-reports@3.2.0:
+    dependencies:
+      html-escaper: 2.0.2
+      istanbul-lib-report: 3.0.1
+
+  js-tokens@10.0.0: {}
+
+  js-tokens@4.0.0: {}
+
+  jsdom@29.1.1:
+    dependencies:
+      '@asamuzakjp/css-color': 5.1.11
+      '@asamuzakjp/dom-selector': 7.1.1
+      '@bramus/specificity': 2.4.2
+      '@csstools/css-syntax-patches-for-csstree': 1.1.7(css-tree@3.2.1)
+      '@exodus/bytes': 1.15.1
+      css-tree: 3.2.1
+      data-urls: 7.0.0
+      decimal.js: 10.6.0
+      html-encoding-sniffer: 6.0.0
+      is-potential-custom-element-name: 1.0.1
+      lru-cache: 11.5.2
+      parse5: 8.0.1
+      saxes: 6.0.0
+      symbol-tree: 3.2.4
+      tough-cookie: 6.0.2
+      undici: 7.29.0
+      w3c-xmlserializer: 5.0.0
+      webidl-conversions: 8.0.1
+      whatwg-mimetype: 5.0.0
+      whatwg-url: 16.0.1
+      xml-name-validator: 5.0.0
+    transitivePeerDependencies:
+      - '@noble/hashes'
+
+  lightningcss-android-arm64@1.33.0:
+    optional: true
+
+  lightningcss-darwin-arm64@1.33.0:
+    optional: true
+
+  lightningcss-darwin-x64@1.33.0:
+    optional: true
+
+  lightningcss-freebsd-x64@1.33.0:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.33.0:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.33.0:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.33.0:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.33.0:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.33.0:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.33.0:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.33.0:
+    optional: true
+
+  lightningcss@1.33.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.33.0
+      lightningcss-darwin-arm64: 1.33.0
+      lightningcss-darwin-x64: 1.33.0
+      lightningcss-freebsd-x64: 1.33.0
+      lightningcss-linux-arm-gnueabihf: 1.33.0
+      lightningcss-linux-arm64-gnu: 1.33.0
+      lightningcss-linux-arm64-musl: 1.33.0
+      lightningcss-linux-x64-gnu: 1.33.0
+      lightningcss-linux-x64-musl: 1.33.0
+      lightningcss-win32-arm64-msvc: 1.33.0
+      lightningcss-win32-x64-msvc: 1.33.0
+
+  lru-cache@11.5.2: {}
+
+  lucide-react@1.25.0(react@19.2.8):
+    dependencies:
+      react: 19.2.8
+
+  lz-string@1.5.0: {}
+
+  magic-string@0.30.21:
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  magicast@0.5.3:
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+      source-map-js: 1.2.1
+
+  make-dir@4.0.0:
+    dependencies:
+      semver: 7.8.5
+
+  mdn-data@2.27.1: {}
+
+  min-indent@1.0.1: {}
+
+  nanoid@3.3.16: {}
+
+  obug@2.1.4: {}
+
+  parse5@8.0.1:
+    dependencies:
+      entities: 8.0.0
+
+  pathe@2.0.3: {}
+
+  picocolors@1.1.1: {}
+
+  picomatch@4.0.5: {}
+
+  playwright-core@1.61.1: {}
+
+  playwright@1.61.1:
+    dependencies:
+      playwright-core: 1.61.1
+    optionalDependencies:
+      fsevents: 2.3.2
+
+  postcss@8.5.24:
+    dependencies:
+      nanoid: 3.3.16
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  pretty-format@27.0.2:
+    dependencies:
+      '@jest/types': 27.0.2
+      ansi-regex: 5.0.1
+      ansi-styles: 5.0.0
+      react-is: 17.0.1
+
+  punycode@2.3.1: {}
+
+  react-dom@19.2.8(react@19.2.8):
+    dependencies:
+      react: 19.2.8
+      scheduler: 0.27.0
+
+  react-is@17.0.1: {}
+
+  react-router-dom@7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
+    dependencies:
+      react: 19.2.8
+      react-dom: 19.2.8(react@19.2.8)
+      react-router: 7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+
+  react-router@7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
+    dependencies:
+      cookie: 1.0.1
+      react: 19.2.8
+      set-cookie-parser: 2.6.0
+    optionalDependencies:
+      react-dom: 19.2.8(react@19.2.8)
+
+  react@19.2.8: {}
+
+  redent@3.0.0:
+    dependencies:
+      indent-string: 4.0.0
+      strip-indent: 3.0.0
+
+  require-from-string@2.0.2: {}
+
+  rolldown@1.1.5:
+    dependencies:
+      '@oxc-project/types': 0.139.0
+      '@rolldown/pluginutils': 1.0.1
+    optionalDependencies:
+      '@rolldown/binding-android-arm64': 1.1.5
+      '@rolldown/binding-darwin-arm64': 1.1.5
+      '@rolldown/binding-darwin-x64': 1.1.5
+      '@rolldown/binding-freebsd-x64': 1.1.5
+      '@rolldown/binding-linux-arm-gnueabihf': 1.1.5
+      '@rolldown/binding-linux-arm64-gnu': 1.1.5
+      '@rolldown/binding-linux-arm64-musl': 1.1.5
+      '@rolldown/binding-linux-ppc64-gnu': 1.1.5
+      '@rolldown/binding-linux-s390x-gnu': 1.1.5
+      '@rolldown/binding-linux-x64-gnu': 1.1.5
+      '@rolldown/binding-linux-x64-musl': 1.1.5
+      '@rolldown/binding-openharmony-arm64': 1.1.5
+      '@rolldown/binding-wasm32-wasi': 1.1.5
+      '@rolldown/binding-win32-arm64-msvc': 1.1.5
+      '@rolldown/binding-win32-x64-msvc': 1.1.5
+
+  saxes@6.0.0:
+    dependencies:
+      xmlchars: 2.2.0
+
+  scheduler@0.27.0: {}
+
+  semver@7.8.5: {}
+
+  set-cookie-parser@2.6.0: {}
+
+  siginfo@2.0.0: {}
+
+  source-map-js@1.2.1: {}
+
+  stackback@0.0.2: {}
+
+  std-env@4.2.0: {}
+
+  strip-indent@3.0.0:
+    dependencies:
+      min-indent: 1.0.1
+
+  supports-color@7.1.0:
+    dependencies:
+      has-flag: 4.0.0
+
+  symbol-tree@3.2.4: {}
+
+  tinybench@2.9.0: {}
+
+  tinyexec@1.2.4: {}
+
+  tinyglobby@0.2.17:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.5)
+      picomatch: 4.0.5
+
+  tinyrainbow@3.1.1: {}
+
+  tldts-core@7.4.9: {}
+
+  tldts@7.4.9:
+    dependencies:
+      tldts-core: 7.4.9
+
+  tough-cookie@6.0.2:
+    dependencies:
+      tldts: 7.4.9
+
+  tr46@6.0.0:
+    dependencies:
+      punycode: 2.3.1
+
+  tslib@2.8.1:
+    optional: true
+
+  typescript@7.0.2:
+    optionalDependencies:
+      '@typescript/typescript-aix-ppc64': 7.0.2
+      '@typescript/typescript-darwin-arm64': 7.0.2
+      '@typescript/typescript-darwin-x64': 7.0.2
+      '@typescript/typescript-freebsd-arm64': 7.0.2
+      '@typescript/typescript-freebsd-x64': 7.0.2
+      '@typescript/typescript-linux-arm': 7.0.2
+      '@typescript/typescript-linux-arm64': 7.0.2
+      '@typescript/typescript-linux-loong64': 7.0.2
+      '@typescript/typescript-linux-mips64el': 7.0.2
+      '@typescript/typescript-linux-ppc64': 7.0.2
+      '@typescript/typescript-linux-riscv64': 7.0.2
+      '@typescript/typescript-linux-s390x': 7.0.2
+      '@typescript/typescript-linux-x64': 7.0.2
+      '@typescript/typescript-netbsd-arm64': 7.0.2
+      '@typescript/typescript-netbsd-x64': 7.0.2
+      '@typescript/typescript-openbsd-arm64': 7.0.2
+      '@typescript/typescript-openbsd-x64': 7.0.2
+      '@typescript/typescript-sunos-x64': 7.0.2
+      '@typescript/typescript-win32-arm64': 7.0.2
+      '@typescript/typescript-win32-x64': 7.0.2
+
+  undici-types@8.3.0: {}
+
+  undici@7.29.0: {}
+
+  vite@8.1.5(@types/node@26.1.1):
+    dependencies:
+      lightningcss: 1.33.0
+      picomatch: 4.0.5
+      postcss: 8.5.24
+      rolldown: 1.1.5
+      tinyglobby: 0.2.17
+    optionalDependencies:
+      '@types/node': 26.1.1
+      fsevents: 2.3.3
+
+  vitest@4.1.10(@types/node@26.1.1)(@vitest/coverage-v8@4.1.10)(jsdom@29.1.1)(vite@8.1.5(@types/node@26.1.1)):
+    dependencies:
+      '@vitest/expect': 4.1.10
+      '@vitest/mocker': 4.1.10(vite@8.1.5(@types/node@26.1.1))
+      '@vitest/pretty-format': 4.1.10
+      '@vitest/runner': 4.1.10
+      '@vitest/snapshot': 4.1.10
+      '@vitest/spy': 4.1.10
+      '@vitest/utils': 4.1.10
+      es-module-lexer: 2.3.1
+      expect-type: 1.4.0
+      magic-string: 0.30.21
+      obug: 2.1.4
+      pathe: 2.0.3
+      picomatch: 4.0.5
+      std-env: 4.2.0
+      tinybench: 2.9.0
+      tinyexec: 1.2.4
+      tinyglobby: 0.2.17
+      tinyrainbow: 3.1.1
+      vite: 8.1.5(@types/node@26.1.1)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@types/node': 26.1.1
+      '@vitest/coverage-v8': 4.1.10(vitest@4.1.10)
+      jsdom: 29.1.1
+    transitivePeerDependencies:
+      - msw
+
+  w3c-xmlserializer@5.0.0:
+    dependencies:
+      xml-name-validator: 5.0.0
+
+  webidl-conversions@8.0.1: {}
+
+  whatwg-mimetype@5.0.0: {}
+
+  whatwg-url@16.0.1:
+    dependencies:
+      '@exodus/bytes': 1.15.1
+      tr46: 6.0.0
+      webidl-conversions: 8.0.1
+    transitivePeerDependencies:
+      - '@noble/hashes'
+
+  why-is-node-running@2.3.0:
+    dependencies:
+      siginfo: 2.0.0
+      stackback: 0.0.2
+
+  xml-name-validator@5.0.0: {}
+
+  xmlchars@2.2.0: {}
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index d3ca026f..5e2c0518 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -1,7 +1,6 @@
 import { Navigate, Route, Routes } from "react-router-dom";
 
 import { AppWindow } from "./components/AppWindow";
-import { LandingPage } from "./pages/LandingPage";
 import { ActivationPage } from "./pages/ActivationPage";
 import { AgentDetailPage } from "./pages/AgentDetailPage";
 import { AgentSelectionPage } from "./pages/AgentSelectionPage";
@@ -12,6 +11,7 @@ import { ProfilesPage } from "./pages/ProfilesPage";
 import { ProviderKeyPage } from "./pages/ProviderKeyPage";
 import { ProvidersPage } from "./pages/ProvidersPage";
 import { ReviewPage } from "./pages/ReviewPage";
+import { I18nProvider } from "./i18n";
 import { WizardProvider, useWizard } from "./state/WizardContext";
 
 function SetupGuard({ stage, children }: { stage: "mode" | "provider" | "model" | "review" | "activation"; children: React.ReactNode }) {
@@ -39,33 +39,11 @@ function SetupGuard({ stage, children }: { stage: "mode" | "provider" | "model"
   return children;
 }
 
-function LandingRoute() {
-  const { state } = useWizard();
-  // Wait for the first status read before choosing. The fetch starts in an
-  // effect, so the initial render has no status and a state of "idle" rather
-  // than "loading" — treating that as "nothing configured" would show the
-  // landing page to a returning user before their Agents ever loaded.
-  if (!state.status && state.statusState !== "error") {
-    return <div className="loading-block"><span className="spinner" />正在读取环境状态</div>;
-  }
-  // An Agent already pointed somewhere, or a previously activated profile,
-  // means this is a returning user: send them to their own environment. The
-  // landing page is for someone who has not configured anything yet, and has
-  // nothing to tell a user whose Agents are already running.
-  const configured =
-    Boolean(state.status?.environment) ||
-    Object.values(state.status?.agents ?? {}).some((agent) => agent.provider);
-  if (configured) {
-    return <Navigate to="/overview" replace />;
-  }
-  return <LandingPage />;
-}
-
-/** The product itself: every route that belongs inside the app window. */
 function WorkspaceRoutes() {
   return (
     <AppWindow>
       <Routes>
+        <Route path="/" element={<Navigate to="/overview" replace />} />
         <Route path="/setup/agents" element={<AgentSelectionPage />} />
         <Route path="/setup/mode" element={<SetupGuard stage="mode"><ConfigModePage /></SetupGuard>} />
         <Route path="/setup/provider" element={<SetupGuard stage="provider"><ProviderKeyPage /></SetupGuard>} />
@@ -75,6 +53,7 @@ function WorkspaceRoutes() {
         <Route path="/overview" element={<EnvironmentOverviewPage />} />
         <Route path="/agents/:agentId" element={<AgentDetailPage />} />
         <Route path="/providers" element={<ProvidersPage />} />
+        <Route path="/providers/new" element={<ProvidersPage create />} />
         <Route path="/profiles" element={<ProfilesPage />} />
         <Route path="*" element={<Navigate to="/setup/agents" replace />} />
       </Routes>
@@ -83,15 +62,11 @@ function WorkspaceRoutes() {
 }
 
 export default function App() {
-  // One provider around both, because "/" has to read status to know whether
-  // this is a returning user. The landing page renders outside AppWindow: it is
-  // a full-page document, not a view inside the app's window chrome.
   return (
-    <WizardProvider>
-      <Routes>
-        <Route path="/" element={<LandingRoute />} />
-        <Route path="*" element={<WorkspaceRoutes />} />
-      </Routes>
-    </WizardProvider>
+    <I18nProvider>
+      <WizardProvider>
+        <WorkspaceRoutes />
+      </WizardProvider>
+    </I18nProvider>
   );
 }
diff --git a/frontend/src/api/client.test.ts b/frontend/src/api/client.test.ts
deleted file mode 100644
index 6421fb8c..00000000
--- a/frontend/src/api/client.test.ts
+++ /dev/null
@@ -1,189 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-import { api, describeError, OneAgentApiError } from "./client";
-
-function jsonResponse(payload: object, status = 200) {
-  return new Response(JSON.stringify(payload), {
-    status,
-    headers: { "Content-Type": "application/json" },
-  });
-}
-
-describe("api client", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it("loads status with same-origin credentials", async () => {
-    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(jsonResponse({ apiVersion: 1 }));
-    await expect(api.status()).resolves.toEqual({ apiVersion: 1 });
-    expect(fetchMock).toHaveBeenCalledWith(
-      "/api/status",
-      expect.objectContaining({ credentials: "same-origin" }),
-    );
-  });
-
-  it("maps structured server errors", async () => {
-    vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      jsonResponse({ message: "bad origin", error_code: "INVALID_ORIGIN", retryable: false }, 403),
-    );
-    await expect(api.status()).rejects.toMatchObject({
-      message: "bad origin",
-      code: "INVALID_ORIGIN",
-      retryable: false,
-      status: 403,
-    });
-  });
-
-  it("falls back through error, then a generic message", async () => {
-    // A proxy or a crash can return a body without the structured fields; the
-    // wizard must still surface something actionable rather than "undefined".
-    vi.spyOn(globalThis, "fetch").mockResolvedValue(jsonResponse({ error: "boom" }, 500));
-    await expect(api.status()).rejects.toMatchObject({
-      message: "boom",
-      code: "INTERNAL_ERROR",
-      retryable: false,
-      status: 500,
-    });
-  });
-
-  it("survives an error body with no recognisable fields", async () => {
-    vi.spyOn(globalThis, "fetch").mockResolvedValue(jsonResponse({}, 502));
-    await expect(api.status()).rejects.toMatchObject({
-      message: "OneAgent request failed",
-      code: "INTERNAL_ERROR",
-      status: 502,
-    });
-  });
-
-  it("wraps a network failure instead of leaking the raw TypeError", async () => {
-    // The common cause is the local GUI process having exited; the user must
-    // see an actionable Chinese message, not "Failed to fetch".
-    vi.spyOn(globalThis, "fetch").mockRejectedValue(new TypeError("Failed to fetch"));
-    await expect(api.status()).rejects.toMatchObject({
-      name: "OneAgentApiError",
-      message: expect.stringContaining("无法连接本机 OneAgent 服务"),
-      retryable: true,
-    });
-  });
-
-  it("wraps a non-JSON response body", async () => {
-    vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      new Response("<html>proxy error</html>", { status: 502, headers: { "Content-Type": "text/html" } }),
-    );
-    await expect(api.status()).rejects.toMatchObject({
-      name: "OneAgentApiError",
-      message: expect.stringContaining("HTTP 502"),
-      status: 502,
-    });
-  });
-
-  it("describes errors preserving the API contract, with a fallback otherwise", () => {
-    const apiError = new OneAgentApiError("key rejected", "API_KEY_REJECTED", false, 401);
-    expect(describeError(apiError, "fallback")).toEqual({
-      message: "key rejected",
-      code: "API_KEY_REJECTED",
-      retryable: false,
-    });
-    expect(describeError(new Error("boom"), "fallback")).toEqual({
-      message: "boom",
-      code: "INTERNAL_ERROR",
-      retryable: true,
-    });
-    expect(describeError("not-an-error", "fallback")).toEqual({
-      message: "fallback",
-      code: "INTERNAL_ERROR",
-      retryable: true,
-    });
-  });
-
-  it("posts provider requests using API field names", async () => {
-    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      jsonResponse({ ok: true, reachable: true, status: 200, message: "ok", error_code: null, retryable: false }),
-    );
-    await api.probe({ provider: "custom", apiBaseUrl: "http://127.0.0.1:9000", apiKey: "sentinel", model: "model-a" });
-    const init = fetchMock.mock.calls[0][1] as RequestInit;
-    expect(init.method).toBe("POST");
-    expect(JSON.parse(String(init.body))).toEqual({
-      provider: "custom",
-      api_base_url: "http://127.0.0.1:9000",
-      api_key: "sentinel",
-      model: "model-a",
-    });
-  });
-
-  it("sends the selected agents so each protocol is probed", async () => {
-    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      jsonResponse({ ok: true, reachable: true, status: 200, message: "ok", error_code: null, retryable: false }),
-    );
-    await api.probe({
-      provider: "custom",
-      apiBaseUrl: "http://127.0.0.1:9000",
-      apiKey: "sentinel",
-      model: "model-a",
-      agents: ["codex", "opencode"],
-    });
-    const init = fetchMock.mock.calls[0][1] as RequestInit;
-    expect(JSON.parse(String(init.body)).agents).toEqual(["codex", "opencode"]);
-  });
-
-  it("omits agents entirely when none are selected", async () => {
-    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      jsonResponse({ ok: true, reachable: true, status: 200, message: "ok", error_code: null, retryable: false }),
-    );
-    await api.probe({ provider: "ppio", apiBaseUrl: "", apiKey: "sentinel", model: "m", agents: [] });
-    const body = JSON.parse(String((fetchMock.mock.calls[0][1] as RequestInit).body));
-    expect(body).not.toHaveProperty("agents");
-  });
-
-  it("includes small_fast_model on activate only when provided", async () => {
-    // A fresh response per call: a Response body can only be read once, and this
-    // test exercises activate twice.
-    const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(() =>
-      Promise.resolve(
-        jsonResponse({ ok: true, agent: "claude-code", config: "/c", provider: "ppio", model: "m", restart: "r", next: "n" }),
-      ),
-    );
-    await api.activateAgent("claude-code", {
-      provider: "ppio",
-      apiBaseUrl: "",
-      apiKey: "sentinel",
-      model: "model-a",
-      smallFastModel: "model-fast",
-    });
-    let body = JSON.parse(String((fetchMock.mock.calls[0][1] as RequestInit).body));
-    expect(body.small_fast_model).toBe("model-fast");
-
-    // Empty falls back to the main model on the backend, so the field is omitted
-    // rather than sent blank.
-    await api.activateAgent("claude-code", {
-      provider: "ppio",
-      apiBaseUrl: "",
-      apiKey: "sentinel",
-      model: "model-a",
-    });
-    body = JSON.parse(String((fetchMock.mock.calls[1][1] as RequestInit).body));
-    expect(body).not.toHaveProperty("small_fast_model");
-  });
-
-  it("supports models, install and register endpoints", async () => {
-    const fetchMock = vi.spyOn(globalThis, "fetch")
-      .mockResolvedValueOnce(jsonResponse({ ok: true, models: ["a"] }))
-      .mockResolvedValueOnce(jsonResponse({ ok: true, code: 0, results: [], log: "", next: "", probe: null }))
-      .mockResolvedValueOnce(jsonResponse({ ok: true, url: "https://ppio.com/", message: "opened" }));
-
-    await api.models({ provider: "ppio", apiBaseUrl: "", apiKey: "key" });
-    await api.install({
-      agents: ["codex"],
-      provider: "ppio",
-      api_key: "key",
-      model: "model-a",
-      configure: true,
-      install_agent: false,
-      skip_test: true,
-    });
-    await api.openRegister("ppio", ["codex"]);
-
-    expect(fetchMock.mock.calls.map(([path]) => path)).toEqual(["/api/models", "/api/install", "/api/open-register"]);
-  });
-});
diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts
deleted file mode 100644
index 544286a6..00000000
--- a/frontend/src/api/client.ts
+++ /dev/null
@@ -1,129 +0,0 @@
-import type {
-  ActivateAgentResponse,
-  InstallRequest,
-  InstallResponse,
-  ModelsResponse,
-  ProbeResponse,
-  ProviderId,
-  StatusResponse,
-} from "../types/api";
-
-export class OneAgentApiError extends Error {
-  readonly code: string;
-  readonly retryable: boolean;
-  readonly status: number;
-
-  constructor(message: string, code: string, retryable: boolean, status: number) {
-    super(message);
-    this.name = "OneAgentApiError";
-    this.code = code;
-    this.retryable = retryable;
-    this.status = status;
-  }
-}
-
-export interface FailureDetail {
-  message: string;
-  code: string;
-  retryable: boolean;
-}
-
-/** Normalise any thrown value into the API error contract, so callers keep
- *  the backend's error_code/retryable instead of hard-coding replacements. */
-export function describeError(error: unknown, fallback: string): FailureDetail {
-  if (error instanceof OneAgentApiError) {
-    return { message: error.message, code: error.code, retryable: error.retryable };
-  }
-  return { message: error instanceof Error ? error.message : fallback, code: "INTERNAL_ERROR", retryable: true };
-}
-
-async function request<T>(path: string, init?: RequestInit): Promise<T> {
-  let response: Response;
-  try {
-    response = await fetch(path, {
-      ...init,
-      credentials: "same-origin",
-      headers: {
-        "Content-Type": "application/json",
-        ...init?.headers,
-      },
-    });
-  } catch {
-    // fetch rejects with an opaque English TypeError on network failure; the
-    // usual cause for this loopback-only app is the GUI process having exited.
-    throw new OneAgentApiError("无法连接本机 OneAgent 服务，请确认它仍在运行", "INTERNAL_ERROR", true, 0);
-  }
-  let payload: T & {
-    message?: string;
-    error?: string;
-    error_code?: string;
-    retryable?: boolean;
-  };
-  try {
-    payload = (await response.json()) as typeof payload;
-  } catch {
-    throw new OneAgentApiError(`服务响应异常（HTTP ${response.status}）`, "INTERNAL_ERROR", false, response.status);
-  }
-  if (!response.ok) {
-    throw new OneAgentApiError(
-      payload.message || payload.error || "OneAgent request failed",
-      payload.error_code || "INTERNAL_ERROR",
-      Boolean(payload.retryable),
-      response.status,
-    );
-  }
-  return payload;
-}
-
-function post<T>(path: string, body: object): Promise<T> {
-  return request<T>(path, { method: "POST", body: JSON.stringify(body) });
-}
-
-export const api = {
-  status: () => request<StatusResponse>("/api/status"),
-  probe: (input: {
-    provider: ProviderId;
-    apiBaseUrl: string;
-    apiKey: string;
-    model: string;
-    /** Selected Agents, so each one's protocol is exercised rather than
-     *  assuming OpenAI Chat Completions for everything. */
-    agents?: string[];
-  }) =>
-    post<ProbeResponse>("/api/probe", {
-      provider: input.provider,
-      api_base_url: input.apiBaseUrl,
-      api_key: input.apiKey,
-      model: input.model,
-      ...(input.agents?.length ? { agents: input.agents } : {}),
-    }),
-  models: (input: { provider: ProviderId; apiBaseUrl: string; apiKey: string }) =>
-    post<ModelsResponse>("/api/models", {
-      provider: input.provider,
-      api_base_url: input.apiBaseUrl,
-      api_key: input.apiKey,
-    }),
-  install: (input: InstallRequest) => post<InstallResponse>("/api/install", input),
-  openRegister: (provider: Exclude<ProviderId, "custom">, agents: string[]) =>
-    post<{ ok: true; url: string; message: string }>("/api/open-register", { provider, agents }),
-  /** Repoint one Agent. Only that Agent's config and credential file change. */
-  activateAgent: (
-    agentId: string,
-    input: {
-      provider: ProviderId;
-      apiBaseUrl: string;
-      apiKey: string;
-      model: string;
-      profileId?: string;
-      smallFastModel?: string;
-    },
-  ) =>
-    post<ActivateAgentResponse>(`/api/agents/${encodeURIComponent(agentId)}/activate`, {
-      provider: input.provider,
-      api_base_url: input.apiBaseUrl,
-      api_key: input.apiKey,
-      model: input.model,
-      ...(input.profileId ? { profile_id: input.profileId } : {}),
-      ...(input.smallFastModel ? { small_fast_model: input.smallFastModel } : {}),
-    }),
-};
diff --git a/frontend/src/backend/api.ts b/frontend/src/backend/api.ts
new file mode 100644
index 00000000..862a638a
--- /dev/null
+++ b/frontend/src/backend/api.ts
@@ -0,0 +1,16 @@
+import { wailsApi } from "./wails";
+import { OneAgentApiError, describeError } from "./errors";
+
+/**
+ * The single page-facing backend surface.
+ *
+ * Every call goes through the generated Wails bindings to a registered Go
+ * service. There is no HTTP transport and no runtime transport selection: the
+ * desktop app does not open a business port, so a bridge failure is a real
+ * failure rather than something to retry over a second channel.
+ */
+export type BackendApi = typeof wailsApi;
+
+export const api: BackendApi = wailsApi;
+
+export { OneAgentApiError, describeError };
diff --git a/frontend/src/backend/errors.ts b/frontend/src/backend/errors.ts
new file mode 100644
index 00000000..aadc13e9
--- /dev/null
+++ b/frontend/src/backend/errors.ts
@@ -0,0 +1,31 @@
+export class OneAgentApiError extends Error {
+	readonly code: string;
+	readonly retryable: boolean;
+	readonly status: number;
+
+	constructor(message: string, code: string, retryable: boolean, status: number) {
+		super(message);
+		this.name = "OneAgentApiError";
+		this.code = code;
+		this.retryable = retryable;
+		this.status = status;
+	}
+}
+
+export interface FailureDetail {
+	message: string;
+	code: string;
+	retryable: boolean;
+}
+
+/** Normalize any thrown value into the stable frontend error contract. */
+export function describeError(error: unknown, fallback: string): FailureDetail {
+	if (error instanceof OneAgentApiError) {
+		return { message: error.message, code: error.code, retryable: error.retryable };
+	}
+	return {
+		message: error instanceof Error ? error.message : fallback,
+		code: "INTERNAL_ERROR",
+		retryable: true,
+	};
+}
diff --git a/frontend/src/backend/wails.test.ts b/frontend/src/backend/wails.test.ts
new file mode 100644
index 00000000..746734cb
--- /dev/null
+++ b/frontend/src/backend/wails.test.ts
@@ -0,0 +1,122 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { InstallResponse, ModelsResponse, ProbeResponse, ProfileSummary, ProviderEntry, StatusResponse } from "../types/api";
+import { LOCALE_STORAGE_KEY } from "../i18n";
+
+const bridge = vi.hoisted(() => ({
+  status: vi.fn(),
+  probe: vi.fn(),
+  models: vi.fn(),
+  getProvider: vi.fn(),
+  saveProvider: vi.fn(),
+  deleteProvider: vi.fn(),
+  install: vi.fn(),
+  register: vi.fn(),
+  activate: vi.fn(),
+  profiles: vi.fn(),
+  saveProfile: vi.fn(),
+  eventsOn: vi.fn(),
+}));
+
+vi.mock("@wailsio/runtime", () => ({ Events: { On: bridge.eventsOn } }));
+vi.mock("../../bindings/github.com/MaimoryLab/OneAgent/internal/binding/statusservice.js", () => ({ GetStatus: bridge.status }));
+vi.mock("../../bindings/github.com/MaimoryLab/OneAgent/internal/binding/providerservice.js", () => ({
+  Probe: bridge.probe,
+  ListModels: bridge.models,
+  OpenRegistration: bridge.register,
+  GetProvider: bridge.getProvider,
+  SaveProvider: bridge.saveProvider,
+  DeleteProvider: bridge.deleteProvider,
+}));
+vi.mock("../../bindings/github.com/MaimoryLab/OneAgent/internal/binding/agentservice.js", () => ({
+  Install: bridge.install,
+  Activate: bridge.activate,
+}));
+vi.mock("../../bindings/github.com/MaimoryLab/OneAgent/internal/binding/profileservice.js", () => ({
+  ListProfiles: bridge.profiles,
+  SaveProfile: bridge.saveProfile,
+}));
+
+import { INSTALL_OUTPUT_EVENT, normalizeWailsError, onInstallOutput, wailsApi } from "./wails";
+
+describe("Wails backend adapter", () => {
+  afterEach(() => vi.resetAllMocks());
+
+  it("forwards the page-facing calls to generated bindings", async () => {
+    const status = {
+      apiVersion: 1,
+      platform: { os: "linux", arch: "arm64", shell: "bash" },
+      runtimes: [],
+      capabilities: { canInstall: {}, missingRuntime: {}, supportedAgentIds: [] },
+      agents: {}, catalog: [], groups: [], providers: {}, mirrors: [], paths: {}, backups: {},
+      profiles: [], activeProfile: null, environment: null, environmentError: null,
+    } satisfies StatusResponse;
+    const probe = { ok: true, reachable: true, status: 204, message: "ok", error_code: null, retryable: false } satisfies ProbeResponse;
+    const models = { ...probe, models: ["model-a"] } satisfies ModelsResponse;
+    const install = { ok: true, code: 0, results: [], log: "", next: "", probe: null } satisfies InstallResponse;
+    const profile = { id: "team", label: "Team", provider: "ppio", baseUrl: null, model: "m", agentIds: ["codex"], activatedAt: null, hasKey: true } satisfies ProfileSummary;
+    const provider = { id: "acme", name: "Acme", home: "", base_url: "https://api.acme.test", anthropic_base_url: "", api_key: "secret", built_in: false } satisfies ProviderEntry;
+
+    bridge.status.mockResolvedValue(status);
+    bridge.probe.mockResolvedValue(probe);
+    bridge.models.mockResolvedValue(models);
+    bridge.install.mockResolvedValue(install);
+    bridge.register.mockResolvedValue({ ok: true, url: "https://ppio.com/", message: "opened" });
+    bridge.activate.mockResolvedValue({ ok: true, agent: "codex", config: "/c", provider: "ppio", model: "m", restart: "restart", next: "next" });
+    bridge.profiles.mockResolvedValue([profile]);
+    bridge.saveProfile.mockResolvedValue(profile);
+    bridge.getProvider.mockResolvedValue(provider);
+    bridge.saveProvider.mockResolvedValue(provider);
+    bridge.deleteProvider.mockResolvedValue({ ok: true });
+
+    await expect(wailsApi.status()).resolves.toBe(status);
+    await expect(wailsApi.probe({ provider: "custom", apiBaseUrl: "https://proxy.test/v1", apiKey: "secret", model: "m", agents: [] })).resolves.toBe(probe);
+    await expect(wailsApi.models({ provider: "ppio", apiBaseUrl: "", apiKey: "secret" })).resolves.toBe(models);
+    await expect(wailsApi.getProvider("acme")).resolves.toBe(provider);
+    await expect(wailsApi.saveProvider({ id: "acme", name: "Acme", home: "", base_url: "https://api.acme.test", anthropic_base_url: "", api_key: "secret" })).resolves.toBe(provider);
+    await expect(wailsApi.deleteProvider("acme")).resolves.toBeUndefined();
+    await expect(wailsApi.install({ agents: ["codex"], provider: "ppio", api_key: "secret", model: "m", configure: true, install_agent: false, skip_test: true })).resolves.toBe(install);
+    await wailsApi.openRegister("ppio", []);
+    await wailsApi.activateAgent("codex", { provider: "ppio", apiBaseUrl: "", apiKey: "secret", model: "m" });
+    await expect(wailsApi.listProfiles()).resolves.toEqual([profile]);
+    await expect(wailsApi.saveProfile({ id: "team", label: "Team", provider: "ppio", apiBaseUrl: "", apiKey: "secret", model: "m", configMode: "provider", agentIds: ["codex"] })).resolves.toBe(profile);
+
+    expect(bridge.probe).toHaveBeenCalledWith({ provider: "custom", api_base_url: "https://proxy.test/v1", api_key: "secret", model: "m", agents: null });
+    expect(bridge.getProvider).toHaveBeenCalledWith({ id: "acme" });
+    expect(bridge.deleteProvider).toHaveBeenCalledWith({ id: "acme" });
+    expect(bridge.install).toHaveBeenCalledWith(expect.objectContaining({ agents: ["codex"], profile_agents: null, timeout: 180, latest: false }));
+    expect(bridge.register).toHaveBeenCalledWith({ provider: "ppio", agents: null });
+    expect(bridge.activate).toHaveBeenCalledWith(expect.objectContaining({ agent_id: "codex", profile_id: "", small_fast_model: "" }));
+    expect(bridge.saveProfile).toHaveBeenCalledWith(expect.objectContaining({ api_base_url: "", api_key: "secret", agent_ids: ["codex"] }));
+  });
+
+  it("restores structured Wails errors without exposing raw bridge details", async () => {
+    expect(normalizeWailsError({ cause: { error_code: "API_KEY_REJECTED", message: "key rejected", status: 401, retryable: false } })).toMatchObject({
+      message: "key rejected", code: "API_KEY_REJECTED", status: 401, retryable: false,
+    });
+    expect(normalizeWailsError({ cause: '{"error_code":"TIMEOUT","message":"probe timed out","status":504,"retryable":true}' })).toMatchObject({
+      message: "probe timed out", code: "TIMEOUT", status: 504, retryable: true,
+    });
+    localStorage.setItem(LOCALE_STORAGE_KEY, "zh-CN");
+    expect(normalizeWailsError(new Error("secret-key-value"))).toMatchObject({
+      message: "无法调用本机 OneAgent 服务", code: "INTERNAL_ERROR", status: 500, retryable: true,
+    });
+  });
+
+  it("subscribes to and filters installation output events", () => {
+    const unsubscribe = vi.fn();
+    const listener = vi.fn();
+    bridge.eventsOn.mockImplementation((_name, callback) => {
+      callback({ data: { kind: "command", args: ["npm"] } });
+      callback({ data: { kind: "output", stream: "stdout", text: "ready" } });
+      callback({ data: null });
+      callback({ data: "ignored" });
+      callback({ data: { kind: "other" } });
+      return unsubscribe;
+    });
+
+    expect(onInstallOutput(listener)).toBe(unsubscribe);
+    expect(bridge.eventsOn).toHaveBeenCalledWith(INSTALL_OUTPUT_EVENT, expect.any(Function));
+    expect(listener).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/frontend/src/backend/wails.ts b/frontend/src/backend/wails.ts
new file mode 100644
index 00000000..58ba5ff4
--- /dev/null
+++ b/frontend/src/backend/wails.ts
@@ -0,0 +1,167 @@
+import { Events } from "@wailsio/runtime";
+
+import * as AgentService from "../../bindings/github.com/MaimoryLab/OneAgent/internal/binding/agentservice.js";
+import * as ProfileService from "../../bindings/github.com/MaimoryLab/OneAgent/internal/binding/profileservice.js";
+import * as ProviderService from "../../bindings/github.com/MaimoryLab/OneAgent/internal/binding/providerservice.js";
+import * as RuntimeService from "../../bindings/github.com/MaimoryLab/OneAgent/internal/binding/runtimeservice.js";
+import * as StatusService from "../../bindings/github.com/MaimoryLab/OneAgent/internal/binding/statusservice.js";
+import type {
+  ActivateAgentResponse,
+  InstallRequest,
+  InstallOutput,
+  InstallResponse,
+  InstallRuntimeResult,
+  ModelsResponse,
+  OpenRegistrationResponse,
+  ProbeResponse,
+  ProviderEntry,
+  ProfileSummary,
+  ProviderId,
+  RuntimeStatus,
+  SaveProviderInput,
+  StatusResponse,
+} from "../types/api";
+import { currentLocale, translate } from "../i18n";
+import { OneAgentApiError } from "./errors";
+
+export { OneAgentApiError, describeError } from "./errors";
+
+export const INSTALL_OUTPUT_EVENT = "oneagent:install-output";
+
+export function onInstallOutput(listener: (output: InstallOutput) => void): () => void {
+  return Events.On(INSTALL_OUTPUT_EVENT, (event) => {
+    const data = event.data;
+    if (!data || typeof data !== "object") return;
+    const kind = (data as { kind?: unknown }).kind;
+    if (kind === "command" || kind === "output") listener(data as InstallOutput);
+  });
+}
+
+type ErrorCause = Record<string, unknown>;
+
+function causeOf(error: unknown): ErrorCause {
+  const cause = error && typeof error === "object" ? (error as { cause?: unknown }).cause : undefined;
+  if (typeof cause === "string") {
+    try {
+      const parsed: unknown = JSON.parse(cause);
+      return parsed && typeof parsed === "object" ? (parsed as ErrorCause) : {};
+    } catch {
+      return {};
+    }
+  }
+  return cause && typeof cause === "object" ? (cause as ErrorCause) : {};
+}
+
+function stringValue(value: unknown, fallback: string): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function numberValue(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+/** Convert a Wails bridge rejection into the stable frontend error contract. */
+export function normalizeWailsError(error: unknown): OneAgentApiError {
+  if (error instanceof OneAgentApiError) return error;
+  const cause = causeOf(error);
+  const known = Object.keys(cause).length > 0;
+  return new OneAgentApiError(
+    known ? stringValue(cause.message, translate(currentLocale(), "OneAgent 请求失败")) : translate(currentLocale(), "无法调用本机 OneAgent 服务"),
+    known ? stringValue(cause.error_code, "INTERNAL_ERROR") : "INTERNAL_ERROR",
+    known ? cause.retryable === true : true,
+    known ? numberValue(cause.status, 500) : 500,
+  );
+}
+
+async function call<T>(operation: () => PromiseLike<T>): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    throw normalizeWailsError(error);
+  }
+}
+
+export const wailsApi = {
+  onInstallOutput,
+  status: (): Promise<StatusResponse> => call(() => StatusService.GetStatus()) as Promise<StatusResponse>,
+  probe: (input: { provider: ProviderId; apiBaseUrl: string; apiKey: string; model: string; agents?: string[] }): Promise<ProbeResponse> =>
+    call(() => ProviderService.Probe({
+      provider: input.provider,
+      api_base_url: input.apiBaseUrl,
+      api_key: input.apiKey,
+      model: input.model,
+      agents: input.agents?.length ? input.agents : null,
+    })) as Promise<ProbeResponse>,
+  models: (input: { provider: ProviderId; apiBaseUrl: string; apiKey: string }): Promise<ModelsResponse> =>
+    call(() => ProviderService.ListModels({
+      provider: input.provider,
+      api_base_url: input.apiBaseUrl,
+      api_key: input.apiKey,
+    })) as Promise<ModelsResponse>,
+  getProvider: (id: string): Promise<ProviderEntry> =>
+    call(() => ProviderService.GetProvider({ id })) as Promise<ProviderEntry>,
+  saveProvider: (input: SaveProviderInput): Promise<ProviderEntry> =>
+    call(() => ProviderService.SaveProvider(input)) as Promise<ProviderEntry>,
+  deleteProvider: (id: string): Promise<void> =>
+    call(() => ProviderService.DeleteProvider({ id })).then(() => undefined),
+  install: (input: InstallRequest): Promise<InstallResponse> =>
+    call(() => AgentService.Install({
+      agents: input.agents,
+      profile_agents: input.profile_agents ?? null,
+      provider: input.provider,
+      api_base_url: input.api_base_url ?? "",
+      api_key: input.api_key,
+      model: input.model,
+      small_fast_model: input.small_fast_model ?? "",
+      profile_id: input.profile_id ?? "",
+      configure: input.configure,
+      install_agent: input.install_agent,
+      locked_version: input.locked_version ?? false,
+      latest: input.latest ?? false,
+      skip_test: input.skip_test,
+      registry: input.registry ?? "",
+      timeout: input.timeout ?? 180,
+    })) as Promise<InstallResponse>,
+  openRegister: (provider: ProviderId, agents: string[]): Promise<OpenRegistrationResponse> =>
+    call(() => ProviderService.OpenRegistration({ provider, agents: agents.length ? agents : null })) as Promise<OpenRegistrationResponse>,
+  activateAgent: (
+    agentId: string,
+    input: { provider: ProviderId; apiBaseUrl: string; apiKey: string; model: string; profileId?: string; smallFastModel?: string },
+  ): Promise<ActivateAgentResponse> =>
+    call(() => AgentService.Activate({
+      agent_id: agentId,
+      provider: input.provider,
+      api_base_url: input.apiBaseUrl,
+      api_key: input.apiKey,
+      model: input.model,
+      profile_id: input.profileId ?? "",
+      small_fast_model: input.smallFastModel ?? "",
+    })) as Promise<ActivateAgentResponse>,
+  listRuntimes: (): Promise<RuntimeStatus[]> =>
+    call(() => RuntimeService.ListRuntimes()).then((runtimes) => runtimes ?? []),
+  installRuntime: (runtime: string): Promise<InstallRuntimeResult> =>
+    call(() => RuntimeService.InstallRuntime({ runtime })) as Promise<InstallRuntimeResult>,
+  listProfiles: (): Promise<ProfileSummary[]> => call(() => ProfileService.ListProfiles()) as Promise<ProfileSummary[]>,
+  saveProfile: (input: {
+    id: string;
+    label: string;
+    provider: ProviderId;
+    apiBaseUrl: string;
+    apiKey: string;
+    model: string;
+    configMode: string;
+    agentIds: string[];
+  }): Promise<ProfileSummary> =>
+    call(() => ProfileService.SaveProfile({
+      id: input.id,
+      label: input.label,
+      provider: input.provider,
+      api_base_url: input.apiBaseUrl,
+      api_key: input.apiKey,
+      model: input.model,
+      config_mode: input.configMode,
+      agent_ids: input.agentIds,
+    })) as Promise<ProfileSummary>,
+};
+
+export type WailsApi = typeof wailsApi;
diff --git a/frontend/src/components/AdvancedSection.tsx b/frontend/src/components/AdvancedSection.tsx
index d40dfb2f..935d1ede 100644
--- a/frontend/src/components/AdvancedSection.tsx
+++ b/frontend/src/components/AdvancedSection.tsx
@@ -2,6 +2,8 @@ import { ChevronDown } from "lucide-react";
 import { useState } from "react";
 import type { PropsWithChildren } from "react";
 
+import { useI18n } from "../i18n";
+
 /**
  * Collapsed-by-default container for options most users should not touch.
  *
@@ -11,15 +13,16 @@ import type { PropsWithChildren } from "react";
  * wondering whether they skipped something they needed.
  */
 export function AdvancedSection({
-  label = "高级选项",
+  label,
   hint,
   children,
 }: PropsWithChildren<{ label?: string; hint?: string }>) {
   const [open, setOpen] = useState(false);
+  const { t } = useI18n();
   return (
     <section className={`advanced-section${open ? " is-open" : ""}`}>
       <button type="button" onClick={() => setOpen((value) => !value)} aria-expanded={open}>
-        {label}
+        {label ?? t("高级选项")}
         <ChevronDown size={15} aria-hidden="true" />
       </button>
       {!open && hint ? <p className="advanced-hint">{hint}</p> : null}
diff --git a/frontend/src/components/AgentManageRow.test.tsx b/frontend/src/components/AgentManageRow.test.tsx
index 141ec219..c78497dc 100644
--- a/frontend/src/components/AgentManageRow.test.tsx
+++ b/frontend/src/components/AgentManageRow.test.tsx
@@ -1,5 +1,5 @@
-import { fireEvent, render, screen } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
 
 import type { AgentCatalogItem, AgentStatus } from "../types/api";
 import { AgentManageRow, compareVersions, isBehind, targetSummary } from "./AgentManageRow";
@@ -27,6 +27,7 @@ function agentStatus(over: Partial<AgentStatus> = {}): AgentStatus {
     lockedVersion: "0.145.0",
     canInstall: true,
     provider: "ppio",
+    profileId: "team",
     model: "deepseek/deepseek-v3",
     baseUrl: "https://api.ppio.com/openai",
     updatedAt: "2026-07-27T00:00:00Z",
@@ -35,7 +36,7 @@ function agentStatus(over: Partial<AgentStatus> = {}): AgentStatus {
   };
 }
 
-function renderRow(over: Partial<AgentStatus> = {}, onOpen = vi.fn()) {
+function renderRow(over: Partial<AgentStatus> = {}, profileName = "团队 PPIO") {
   render(
     <AgentManageRow
       agentId="codex"
@@ -44,23 +45,24 @@ function renderRow(over: Partial<AgentStatus> = {}, onOpen = vi.fn()) {
       providers={{
         ppio: { name: "PPIO", home: "https://ppio.com/", base_url: "https://api.ppio.com/openai" },
       }}
-      onOpen={onOpen}
+      profileName={profileName}
     />,
   );
-  return onOpen;
 }
 
 describe("AgentManageRow", () => {
   it("shows what the Agent is pointed at", () => {
     renderRow();
     expect(screen.getByText("Codex")).toBeTruthy();
-    expect(screen.getByText(/PPIO/)).toBeTruthy();
+    expect(screen.getByText("PPIO", { selector: ".agent-manage-fact > span" })).toBeTruthy();
     expect(screen.getByText(/deepseek\/deepseek-v3/)).toBeTruthy();
+    expect(screen.getByText("团队 PPIO")).toBeTruthy();
   });
 
   it("distinguishes an unconfigured Agent from a configured one", () => {
-    renderRow({ configured: false, provider: null, model: null, baseUrl: null });
-    expect(screen.getByText("未配置")).toBeTruthy();
+    renderRow({ configured: false, provider: null, profileId: null, model: null, baseUrl: null }, "");
+    expect(screen.getAllByText("未记录")).toHaveLength(2);
+    expect(screen.getByText("未绑定")).toBeTruthy();
   });
 
   it("flags a version behind the locked one", () => {
@@ -90,14 +92,11 @@ describe("AgentManageRow", () => {
     expect(isBehind("2.1.220", "2.1.217")).toBe(false);
   });
 
-  it("delegates configuration instead of editing in place", () => {
-    // The form moved to /agents/:agentId. Keeping it here grew the list by a
-    // whole form's height and let several rows sit half-configured at once.
-    const onOpen = renderRow();
+  it("is informational rather than a configuration entry point", () => {
+    renderRow();
     expect(screen.queryByLabelText(/API Key/i)).toBeNull();
     expect(screen.queryByRole("button", { name: /测试连接/ })).toBeNull();
-    fireEvent.click(screen.getByRole("button", { name: /Codex/ }));
-    expect(onOpen).toHaveBeenCalled();
+    expect(screen.queryByRole("button", { name: /Codex/ })).toBeNull();
   });
 });
 
diff --git a/frontend/src/components/AgentManageRow.tsx b/frontend/src/components/AgentManageRow.tsx
index 7e221a4f..e027ff34 100644
--- a/frontend/src/components/AgentManageRow.tsx
+++ b/frontend/src/components/AgentManageRow.tsx
@@ -1,5 +1,4 @@
-import { ChevronRight } from "lucide-react";
-
+import { sourceTranslate, type Translate, useI18n } from "../i18n";
 import type { AgentCatalogItem, AgentStatus, StatusResponse } from "../types/api";
 import { AgentIcon, agentTagline } from "./icons/agents";
 import { StatusBadge } from "./StatusBadge";
@@ -24,7 +23,7 @@ export function isBehind(installed: string, locked: string): boolean {
   return compareVersions(installed, locked) < 0;
 }
 
-export function versionNote(status: AgentStatus): { text: string; behind: boolean } | null {
+export function versionNote(status: AgentStatus, t: Translate = sourceTranslate): { text: string; behind: boolean } | null {
   if (!status.installed || !status.version) return null;
   if (!status.lockedVersion || status.version === status.lockedVersion) {
     // Being current is the normal case and needs no words: the bare version is
@@ -38,7 +37,7 @@ export function versionNote(status: AgentStatus): { text: string; behind: boolea
     // The arrow already says which way this goes.
     return { text: `${status.version} → ${status.lockedVersion}`, behind: true };
   }
-  return { text: `${status.version}（锁定 ${status.lockedVersion}）`, behind: false };
+  return { text: t("{version}（锁定 {lockedVersion}）", { version: status.version, lockedVersion: status.lockedVersion }), behind: false };
 }
 
 /**
@@ -52,10 +51,11 @@ export function versionNote(status: AgentStatus): { text: string; behind: boolea
 export function targetSummary(
   status: AgentStatus,
   providers: Providers,
+  t: Translate = sourceTranslate,
 ): { text: string; note: string } {
   const detected = status.detected;
   if (detected?.unreadable) {
-    return { text: "配置无法解析", note: detected.unreadable };
+    return { text: t("配置无法解析"), note: detected.unreadable };
   }
   const providerName = status.provider ? providers[status.provider]?.name || status.provider : "";
   // Ours, and the file agrees (or has nothing to add).
@@ -64,7 +64,7 @@ export function targetSummary(
       detected && detected.baseUrl && status.baseUrl && detected.baseUrl !== status.baseUrl;
     return {
       text: `${providerName} · ${status.model}`,
-      note: drifted ? `配置文件当前指向 ${detected!.baseUrl}` : "",
+      note: drifted ? t("配置文件当前指向 {url}", { url: detected!.baseUrl }) : "",
     };
   }
   // No record of our own, but the file says something.
@@ -72,56 +72,54 @@ export function targetSummary(
     const parts = [detected.baseUrl, detected.model].filter(Boolean);
     return {
       text: parts.join(" · "),
-      note: detected.managedByOneAgent ? "" : "检测到的配置，非 OneAgent 写入",
+      note: detected.managedByOneAgent ? "" : t("检测到的配置，非 OneAgent 写入"),
     };
   }
-  return { text: "未配置", note: "" };
+  return { text: t("未配置"), note: "" };
 }
 
 /**
- * One row in the overview: what this Agent points at, nothing editable.
- *
- * Configuration lives on /agents/:agentId. Editing inline used to grow the list
- * by the height of a whole form, let several rows sit half-configured at once,
- * and left no room for the file paths and backup state a detail view can show.
+ * One read-only row in the environment overview.
  */
 export function AgentManageRow({
   agentId,
   catalog,
   status,
   providers,
-  onOpen,
+  profileName,
 }: {
   agentId: string;
   catalog: AgentCatalogItem | undefined;
   status: AgentStatus;
   providers: Providers;
-  onOpen: () => void;
+  profileName: string;
 }) {
-  const version = versionNote(status);
-  const target = targetSummary(status, providers);
-  const configuredSomehow =
-    Boolean(status.provider) || Boolean(status.detected?.baseUrl) || Boolean(status.detected?.model);
-  const action = !status.installed ? "安装并配置" : configuredSomehow ? "改配置" : "配置";
+  const { t } = useI18n();
+  const version = versionNote(status, t);
+  const target = targetSummary(status, providers, t);
+  const providerName = status.provider
+    ? providers[status.provider]?.name || status.provider
+    : status.detected?.baseUrl || t("未记录");
+  const model = status.model || status.detected?.model || t("未记录");
 
   return (
-    <button className="agent-manage-row" type="button" onClick={onOpen}>
-      <span className="agent-icon" title={agentTagline(agentId) || undefined}>
+    <div className="agent-manage-row" data-testid={`agent-${agentId}`}>
+      <span className="agent-icon" title={agentTagline(agentId, t) || undefined}>
         <AgentIcon agentId={agentId} size={18} />
       </span>
       <span className="agent-manage-identity">
         <strong>{catalog?.name || agentId}</strong>
-        <span className="agent-manage-target">{target.text}</span>
         {target.note ? <small className="agent-manage-note">{target.note}</small> : null}
       </span>
-      {version ? <span className={`agent-manage-version${version.behind ? " is-behind" : ""}`}>{version.text}</span> : null}
+      <span className="agent-manage-fact"><small>Provider</small><span title={providerName}>{providerName}</span></span>
+      <span className="agent-manage-fact"><small>Profile</small><span title={status.profileId || undefined}>{profileName || t("未绑定")}</span></span>
+      <span className="agent-manage-fact"><small>{t("模型")}</small><span title={model}>{model}</span></span>
+      <span className={`agent-manage-fact agent-manage-version${version?.behind ? " is-behind" : ""}`}>
+        <small>{t("版本")}</small><span>{version?.text || t("未知")}</span>
+      </span>
       <StatusBadge tone={status.installed ? "success" : "warning"}>
-        {status.installed ? "已安装" : "待安装"}
+        {status.installed ? t("已安装") : t("待安装")}
       </StatusBadge>
-      <span className="agent-manage-cta">
-        {action}
-        <ChevronRight size={15} aria-hidden="true" />
-      </span>
-    </button>
+    </div>
   );
 }
diff --git a/frontend/src/components/AgentProgressRow.tsx b/frontend/src/components/AgentProgressRow.tsx
index d30124ad..f8b275cf 100644
--- a/frontend/src/components/AgentProgressRow.tsx
+++ b/frontend/src/components/AgentProgressRow.tsx
@@ -1,5 +1,6 @@
 import { AlertTriangle, CheckCircle2, Circle, LoaderCircle, RotateCcw } from "lucide-react";
 
+import { useI18n } from "../i18n";
 import type { AgentInstallResult } from "../types/api";
 import { StatusBadge } from "./StatusBadge";
 
@@ -14,8 +15,18 @@ export function AgentProgressRow({
   loading: boolean;
   onRetry?: () => void;
 }) {
+  const { t } = useI18n();
   const failed = result?.status === "failed";
   const complete = result && !failed && result.status !== "skipped";
+  const resultStatus = result?.status === "failed"
+    ? t("失败")
+    : result?.status === "skipped"
+      ? t("已跳过")
+      : result?.status === "guide-only"
+        ? t("仅引导")
+        : result?.status === "configured" || result?.status === "installed"
+          ? t("已完成")
+          : result?.status;
   return (
     <div className="progress-row">
       <span className={`progress-icon${failed ? " is-failed" : complete ? " is-complete" : ""}`} aria-hidden="true">
@@ -23,17 +34,17 @@ export function AgentProgressRow({
       </span>
       <span className="progress-copy">
         <strong>{name}</strong>
-        <span>{loading ? "正在处理" : result?.message || result?.status || "等待执行"}</span>
+        <span>{loading ? t("正在处理") : result?.message || resultStatus || t("等待执行")}</span>
       </span>
       {failed && onRetry ? (
         <button className="button button-compact" type="button" onClick={onRetry}>
           <RotateCcw size={15} />
-          重试
+          {t("重试")}
         </button>
       ) : complete ? (
-        <StatusBadge tone="success">已完成</StatusBadge>
+        <StatusBadge tone="success">{t("已完成")}</StatusBadge>
       ) : result?.status === "guide-only" ? (
-        <StatusBadge tone="neutral">仅引导</StatusBadge>
+        <StatusBadge tone="neutral">{t("仅引导")}</StatusBadge>
       ) : null}
     </div>
   );
diff --git a/frontend/src/components/AgentRow.tsx b/frontend/src/components/AgentRow.tsx
index b8049492..26a82c75 100644
--- a/frontend/src/components/AgentRow.tsx
+++ b/frontend/src/components/AgentRow.tsx
@@ -1,3 +1,4 @@
+import { useI18n } from "../i18n";
 import type { AgentCatalogItem, AgentStatus } from "../types/api";
 import { AgentIcon, agentTagline } from "./icons/agents";
 import { StatusBadge } from "./StatusBadge";
@@ -10,8 +11,9 @@ interface AgentRowProps {
 }
 
 export function AgentRow({ agent, status, selected, onToggle }: AgentRowProps) {
+  const { t } = useI18n();
   const supported = agent.platforms.length > 0;
-  const statusLabel = status?.installed ? "已安装" : agent.guideOnly ? "仅引导" : "待安装";
+  const statusLabel = status?.installed ? t("已安装") : agent.guideOnly ? t("仅引导") : t("待安装");
   const statusTone = status?.installed ? "success" : agent.guideOnly ? "neutral" : "warning";
 
   return (
@@ -21,9 +23,9 @@ export function AgentRow({ agent, status, selected, onToggle }: AgentRowProps) {
         checked={selected}
         onChange={onToggle}
         disabled={!supported}
-        aria-label={`选择 ${agent.name}`}
+        aria-label={t("选择 {name}", { name: agent.name })}
       />
-      <span className="agent-icon" title={agentTagline(agent.id) || undefined}>
+      <span className="agent-icon" title={agentTagline(agent.id, t) || undefined}>
         <AgentIcon agentId={agent.id} size={20} />
       </span>
       <span className="agent-copy">
@@ -31,7 +33,7 @@ export function AgentRow({ agent, status, selected, onToggle }: AgentRowProps) {
           <strong>{agent.name}</strong>
           {agent.lockedVersion ? <span className="agent-version">v{agent.lockedVersion}</span> : null}
         </span>
-        <span>{agent.guideOnly ? "显示官方安装与配置步骤" : "支持检测、安装与初始化配置"}</span>
+        <span>{agent.guideOnly ? t("显示官方安装与配置步骤") : t("支持检测、安装与初始化配置")}</span>
         {agent.platformNote ? <small>{agent.platformNote}</small> : null}
       </span>
       <StatusBadge tone={statusTone}>{statusLabel}</StatusBadge>
diff --git a/frontend/src/components/AppWindow.tsx b/frontend/src/components/AppWindow.tsx
index 0e30d8a3..92b62121 100644
--- a/frontend/src/components/AppWindow.tsx
+++ b/frontend/src/components/AppWindow.tsx
@@ -6,12 +6,6 @@ export function AppWindow({ children }: PropsWithChildren) {
   return (
     <div className="desktop-stage">
       <div className="app-window">
-        <div className="window-chrome window-chrome-sidebar" aria-hidden="true">
-          <span className="traffic-light traffic-light-red" />
-          <span className="traffic-light traffic-light-yellow" />
-          <span className="traffic-light traffic-light-green" />
-        </div>
-        <div className="window-chrome window-title">OneAgent</div>
         <NavigationSidebar />
         <main className="app-main">{children}</main>
       </div>
diff --git a/frontend/src/components/ConnectionStatus.tsx b/frontend/src/components/ConnectionStatus.tsx
index 99d57651..5e1a49ae 100644
--- a/frontend/src/components/ConnectionStatus.tsx
+++ b/frontend/src/components/ConnectionStatus.tsx
@@ -1,14 +1,16 @@
 import { AlertCircle, CheckCircle2, LoaderCircle, Radio, ShieldAlert } from "lucide-react";
 
+import { useI18n } from "../i18n";
 import type { AsyncState } from "../state/wizardReducer";
 import type { ProbeResponse } from "../types/api";
 
 export function ConnectionStatus({ state, result }: { state: AsyncState; result: ProbeResponse | null }) {
+  const { t } = useI18n();
   if (state === "idle") {
     return (
       <div className="inline-status status-idle">
         <Radio size={17} />
-        尚未测试连接
+        {t("尚未测试连接")}
       </div>
     );
   }
@@ -16,7 +18,7 @@ export function ConnectionStatus({ state, result }: { state: AsyncState; result:
     return (
       <div className="inline-status status-loading" role="status">
         <LoaderCircle size={17} className="spin" />
-        正在验证端点和 Key
+        {t("正在验证端点和 Key")}
       </div>
     );
   }
@@ -32,7 +34,7 @@ export function ConnectionStatus({ state, result }: { state: AsyncState; result:
   return (
     <div className={`inline-status ${rejected ? "status-warning" : "status-error"}`} role="alert">
       {rejected ? <ShieldAlert size={17} /> : <AlertCircle size={17} />}
-      {result?.message || "连接失败"}
+      {result?.message || t("连接失败")}
     </div>
   );
 }
diff --git a/frontend/src/components/GuideOnlyRow.tsx b/frontend/src/components/GuideOnlyRow.tsx
index 88e58ce5..b9ee228f 100644
--- a/frontend/src/components/GuideOnlyRow.tsx
+++ b/frontend/src/components/GuideOnlyRow.tsx
@@ -1,5 +1,6 @@
 import { ArrowUpRight } from "lucide-react";
 
+import { useI18n } from "../i18n";
 import type { AgentCatalogItem, AgentStatus } from "../types/api";
 import { AgentIcon, agentTagline } from "./icons/agents";
 import { StatusBadge } from "./StatusBadge";
@@ -25,23 +26,24 @@ export function GuideOnlyRow({
   catalog: AgentCatalogItem;
   status: AgentStatus | undefined;
 }) {
+  const { t } = useI18n();
   const detected = Boolean(status?.installed);
   return (
     <div className="agent-manage-row is-guide">
-      <span className="agent-icon" title={agentTagline(agentId) || undefined}>
+      <span className="agent-icon" title={agentTagline(agentId, t) || undefined}>
         <AgentIcon agentId={agentId} size={18} />
       </span>
       <span className="agent-manage-identity">
         <strong>{catalog.name}</strong>
         <span className="agent-manage-target">
-          {catalog.platformNote || "按官方方式安装与登录"}
+          {catalog.platformNote || t("按官方方式安装与登录")}
         </span>
       </span>
       <StatusBadge tone={detected ? "success" : "neutral"}>
-        {detected ? "已检测到" : "官方安装"}
+        {detected ? t("已检测到") : t("官方安装")}
       </StatusBadge>
       <span className="agent-manage-cta is-static">
-        官方文档
+        {t("官方文档")}
         <ArrowUpRight size={14} aria-hidden="true" />
       </span>
     </div>
diff --git a/frontend/src/components/LogDisclosure.tsx b/frontend/src/components/LogDisclosure.tsx
index 08cfd0a1..88cb5049 100644
--- a/frontend/src/components/LogDisclosure.tsx
+++ b/frontend/src/components/LogDisclosure.tsx
@@ -1,14 +1,20 @@
 import { ChevronDown, TerminalSquare } from "lucide-react";
-import { useState } from "react";
+import { useEffect, useState } from "react";
 
-export function LogDisclosure({ log }: { log: string }) {
-  const [open, setOpen] = useState(false);
+import { useI18n } from "../i18n";
+
+export function LogDisclosure({ log, open: openByParent = false }: { log: string; open?: boolean }) {
+  const { t } = useI18n();
+  const [open, setOpen] = useState(openByParent);
+  useEffect(() => {
+    if (openByParent) setOpen(true);
+  }, [openByParent]);
   if (!log) return null;
   return (
     <section className={`log-disclosure${open ? " is-open" : ""}`}>
       <button type="button" onClick={() => setOpen((value) => !value)} aria-expanded={open}>
         <TerminalSquare size={17} />
-        查看安装日志
+        {t("查看安装日志")}
         <ChevronDown size={17} />
       </button>
       {open ? <pre>{log}</pre> : null}
diff --git a/frontend/src/components/ModelPicker.tsx b/frontend/src/components/ModelPicker.tsx
index b8e84c44..efe54d80 100644
--- a/frontend/src/components/ModelPicker.tsx
+++ b/frontend/src/components/ModelPicker.tsx
@@ -1,6 +1,8 @@
 import { Check, Search } from "lucide-react";
 import { useMemo, useState } from "react";
 
+import { useI18n } from "../i18n";
+
 interface ModelPickerProps {
   models: string[];
   value: string;
@@ -8,6 +10,7 @@ interface ModelPickerProps {
 }
 
 export function ModelPicker({ models, value, onChange }: ModelPickerProps) {
+  const { t } = useI18n();
   const [query, setQuery] = useState("");
   const filtered = useMemo(
     () => models.filter((model) => model.toLocaleLowerCase().includes(query.trim().toLocaleLowerCase())),
@@ -20,9 +23,9 @@ export function ModelPicker({ models, value, onChange }: ModelPickerProps) {
         <>
           <div className="search-field">
             <Search size={17} />
-            <input value={query} onChange={(event) => setQuery(event.target.value)} placeholder="搜索模型" aria-label="搜索模型" />
+            <input value={query} onChange={(event) => setQuery(event.target.value)} placeholder={t("搜索模型")} aria-label={t("搜索模型")} />
           </div>
-          <div className="model-list" role="radiogroup" aria-label="模型列表">
+          <div className="model-list" role="radiogroup" aria-label={t("模型列表")}>
             {filtered.map((model) => (
               <button
                 type="button"
@@ -39,14 +42,14 @@ export function ModelPicker({ models, value, onChange }: ModelPickerProps) {
                 {model === value ? <Check size={17} /> : null}
               </button>
             ))}
-            {!filtered.length ? <div className="empty-row">没有匹配的模型</div> : null}
+            {!filtered.length ? <div className="empty-row">{t("没有匹配的模型")}</div> : null}
           </div>
         </>
       ) : null}
 
       <div className="field-stack manual-model-field">
-        <label htmlFor="manual-model">{models.length ? "或手动输入模型 ID" : "手动输入模型 ID"}</label>
-        <input id="manual-model" className="text-field" value={value} onChange={(event) => onChange(event.target.value)} placeholder="例如 gpt-4.1" />
+        <label htmlFor="manual-model">{models.length ? t("或手动输入模型 ID") : t("手动输入模型 ID")}</label>
+        <input id="manual-model" className="text-field" value={value} onChange={(event) => onChange(event.target.value)} placeholder={t("例如 gpt-4.1")} />
       </div>
     </div>
   );
diff --git a/frontend/src/components/NavigationSidebar.tsx b/frontend/src/components/NavigationSidebar.tsx
index 7ef955e4..c03791ce 100644
--- a/frontend/src/components/NavigationSidebar.tsx
+++ b/frontend/src/components/NavigationSidebar.tsx
@@ -1,16 +1,19 @@
-import { Boxes, FolderCog, Gauge, Layers3, Sparkles } from "lucide-react";
+import { Boxes, FolderCog, Gauge, Languages, Layers3 } from "lucide-react";
 import { NavLink } from "react-router-dom";
 
+import { type TranslationKey, useI18n } from "../i18n";
+
 // Only real destinations belong here. /setup/* are wizard steps behind
 // SetupGuard: listing them made the sidebar look broken, because clicking one
 // without a selected Agent bounced straight back to the first step.
-const navItems = [
-  { to: "/overview", label: "环境总览", icon: Gauge },
+const navItems: Array<{ to: string; label: TranslationKey | "Provider"; icon: typeof Gauge }> = [
+  { to: "/overview", label: "激活环境", icon: Gauge },
   { to: "/providers", label: "Provider", icon: Layers3 },
   { to: "/profiles", label: "配置模板", icon: FolderCog },
 ];
 
 export function NavigationSidebar() {
+  const { locale, setLocale, t } = useI18n();
   return (
     <aside className="navigation-sidebar">
       <div className="brand-lockup">
@@ -19,28 +22,32 @@ export function NavigationSidebar() {
         </span>
         <div>
           <strong>OneAgent</strong>
-          <span>AI 开发环境</span>
+          <span>{t("Agent 管家")}</span>
         </div>
       </div>
 
-      <nav className="sidebar-nav" aria-label="主导航">
-        <NavLink to="/setup/agents" className="sidebar-primary-action">
-          <Sparkles size={17} />
-          激活环境
-        </NavLink>
-        <div className="sidebar-section-label">工作区</div>
+      <nav className="sidebar-nav" aria-label={t("主导航")}>
+        <div className="sidebar-section-label">{t("工作区")}</div>
         {navItems.map(({ to, label, icon: Icon }) => (
           <NavLink key={to} to={to} className={({ isActive }) => `sidebar-link${isActive ? " is-active" : ""}`}>
             <Icon size={18} strokeWidth={1.8} />
-            <span>{label}</span>
+            <span>{label === "Provider" ? label : t(label)}</span>
           </NavLink>
         ))}
       </nav>
 
-      <div className="sidebar-footnote">
-        <span className="privacy-dot" />
-        配置只保存在本机
-      </div>
+      <label className="language-picker">
+        <Languages size={16} aria-hidden="true" />
+        <span>{t("语言")}</span>
+        <select className="language-select-wide" value={locale} onChange={(event) => setLocale(event.target.value as "zh-CN" | "en")} aria-label={t("语言")}>
+          <option value="zh-CN">中文</option>
+          <option value="en">English</option>
+        </select>
+        <select className="language-select-compact" value={locale} onChange={(event) => setLocale(event.target.value as "zh-CN" | "en")} aria-label={t("语言")}>
+          <option value="zh-CN">中</option>
+          <option value="en">EN</option>
+        </select>
+      </label>
     </aside>
   );
 }
diff --git a/frontend/src/components/PageScaffold.tsx b/frontend/src/components/PageScaffold.tsx
index b5f258f7..ce79b916 100644
--- a/frontend/src/components/PageScaffold.tsx
+++ b/frontend/src/components/PageScaffold.tsx
@@ -1,6 +1,7 @@
 import { ArrowLeft, ArrowRight } from "lucide-react";
 import type { PropsWithChildren, ReactNode } from "react";
 
+import { useI18n } from "../i18n";
 import { SetupStepper } from "./SetupStepper";
 
 interface PageScaffoldProps extends PropsWithChildren {
@@ -28,7 +29,7 @@ export function PageScaffold({
   description,
   stepper,
   footerNote,
-  backLabel = "返回",
+  backLabel,
   onBack,
   primaryLabel,
   onPrimary,
@@ -38,6 +39,7 @@ export function PageScaffold({
   bodyClassName = "",
   children,
 }: PageScaffoldProps) {
+  const { t } = useI18n();
   return (
     <section className="page-scaffold">
       <header className="page-header">
@@ -56,7 +58,7 @@ export function PageScaffold({
           {onBack ? (
             <button className="button button-secondary" type="button" onClick={onBack}>
               <ArrowLeft size={16} />
-              {backLabel}
+              {backLabel ?? t("返回")}
             </button>
           ) : null}
           {footerNote ? <div className="footer-note">{footerNote}</div> : null}
diff --git a/frontend/src/components/ProviderSegment.tsx b/frontend/src/components/ProviderSegment.tsx
index 14b8fac2..fd0111f1 100644
--- a/frontend/src/components/ProviderSegment.tsx
+++ b/frontend/src/components/ProviderSegment.tsx
@@ -1,26 +1,33 @@
-import type { ProviderId } from "../types/api";
+import { Plus } from "lucide-react";
 
-const providers: Array<{ id: ProviderId; label: string }> = [
-  { id: "ppio", label: "PPIO" },
-  { id: "novita", label: "Novita" },
-  { id: "custom", label: "自定义" },
-];
+import { useI18n } from "../i18n";
+import type { ProviderId, StatusResponse } from "../types/api";
 
-export function ProviderSegment({ value, onChange }: { value: ProviderId; onChange: (value: ProviderId) => void }) {
+export function ProviderSegment({
+  value,
+  providers,
+  onAdd,
+  onChange,
+}: {
+  value: ProviderId;
+  providers: StatusResponse["providers"];
+  onAdd: () => void;
+  onChange: (value: ProviderId) => void;
+}) {
+  const { t } = useI18n();
   return (
-    <div className="provider-segment" role="radiogroup" aria-label="模型服务">
-      {providers.map((provider) => (
-        <button
-          key={provider.id}
-          type="button"
-          role="radio"
-          aria-checked={value === provider.id}
-          className={value === provider.id ? "is-selected" : ""}
-          onClick={() => onChange(provider.id)}
-        >
-          {provider.label}
+    <div className="provider-picker">
+      <label htmlFor="provider-select">{t("模型服务")}</label>
+      <div className="provider-picker-control">
+        <select id="provider-select" value={value} onChange={(event) => onChange(event.target.value)}>
+          {Object.entries(providers)
+            .sort(([first], [second]) => first.localeCompare(second))
+            .map(([id, provider]) => <option key={id} value={id}>{provider.name}</option>)}
+        </select>
+        <button className="provider-add-button" type="button" onClick={onAdd} aria-label={t("新增 Provider")} title={t("新增 Provider")}>
+          <Plus size={17} />
         </button>
-      ))}
+      </div>
     </div>
   );
 }
diff --git a/frontend/src/components/RuntimePrompt.tsx b/frontend/src/components/RuntimePrompt.tsx
new file mode 100644
index 00000000..eaf8d89e
--- /dev/null
+++ b/frontend/src/components/RuntimePrompt.tsx
@@ -0,0 +1,82 @@
+import { Download, RefreshCw, TriangleAlert } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { api, describeError } from "../backend/api";
+import { useI18n } from "../i18n";
+import type { AgentStatus, RuntimeStatus } from "../types/api";
+
+interface RuntimePromptProps {
+  runtimes: RuntimeStatus[];
+  /** Agent id -> runtime id, as reported by capabilities.missingRuntime. */
+  missingRuntime: Record<string, string>;
+  selectedAgentIds: string[];
+  agents: Record<string, AgentStatus>;
+  onInstalled: () => void | Promise<void>;
+}
+
+/**
+ * Prompts for the runtimes the current selection needs. Activation installs a
+ * missing runtime on its own, so this is an early, explicit offer rather than a
+ * gate: nothing here blocks continuing.
+ */
+export function RuntimePrompt({ runtimes, missingRuntime, selectedAgentIds, agents, onInstalled }: RuntimePromptProps) {
+  const { t } = useI18n();
+  const [pending, setPending] = useState("");
+  const [failure, setFailure] = useState("");
+
+  const required = useMemo(() => {
+    const byId = new Map(runtimes.map((runtime) => [runtime.id, runtime]));
+    const needed = new Map<string, RuntimeStatus>();
+    for (const agentId of selectedAgentIds) {
+      // An Agent that is already installed does not need its package manager.
+      if (agents[agentId]?.installed) continue;
+      const runtimeId = missingRuntime[agentId];
+      if (!runtimeId) continue;
+      const runtime = byId.get(runtimeId);
+      if (runtime && !runtime.installed && runtime.supported) needed.set(runtimeId, runtime);
+    }
+    return [...needed.values()];
+  }, [agents, missingRuntime, runtimes, selectedAgentIds]);
+
+  if (!required.length) return null;
+
+  const install = async (runtimeId: string) => {
+    setPending(runtimeId);
+    setFailure("");
+    try {
+      await api.installRuntime(runtimeId);
+      await onInstalled();
+    } catch (error) {
+      setFailure(describeError(error, t("运行时安装失败")).message);
+    } finally {
+      setPending("");
+    }
+  };
+
+  return (
+    <div className="notice notice-warning runtime-prompt">
+      <TriangleAlert size={16} aria-hidden="true" />
+      <div className="runtime-prompt-body">
+        <strong>{t("需要先安装运行时")}</strong>
+        <span>{t("所选 Agent 通过 {runtimes} 安装，本机还没有。现在安装，或在激活时自动安装。", { runtimes: required.map((runtime) => runtime.name).join("、") })}</span>
+        <div className="runtime-prompt-actions">
+          {required.map((runtime) => (
+            <button
+              key={runtime.id}
+              className="button button-secondary"
+              type="button"
+              onClick={() => void install(runtime.id)}
+              disabled={Boolean(pending)}
+            >
+              {pending === runtime.id ? <RefreshCw size={15} className="spin" /> : <Download size={15} />}
+              {pending === runtime.id
+                ? t("安装中")
+                : t("安装 {name} {version}", { name: runtime.name, version: runtime.lockedVersion })}
+            </button>
+          ))}
+        </div>
+        {failure ? <span className="runtime-prompt-error">{failure}</span> : null}
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/components/RuntimeSection.test.tsx b/frontend/src/components/RuntimeSection.test.tsx
new file mode 100644
index 00000000..e6343738
--- /dev/null
+++ b/frontend/src/components/RuntimeSection.test.tsx
@@ -0,0 +1,136 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { OneAgentApiError } from "../backend/errors";
+import type { RuntimeStatus } from "../types/api";
+import { RuntimePrompt } from "./RuntimePrompt";
+import { RuntimeSection } from "./RuntimeSection";
+
+const installRuntime = vi.fn();
+
+vi.mock("../backend/api", async () => {
+  const errors = await import("../backend/errors");
+  return {
+    api: { installRuntime: (runtime: string) => installRuntime(runtime) },
+    describeError: errors.describeError,
+  };
+});
+
+function runtime(overrides: Partial<RuntimeStatus> = {}): RuntimeStatus {
+  return {
+    id: "node",
+    name: "Node.js",
+    command: "npm",
+    installed: false,
+    version: "",
+    lockedVersion: "24.18.1",
+    managed: false,
+    supported: true,
+    note: "",
+    license: "MIT",
+    licenseUrl: "https://example.test/license",
+    source: "https://nodejs.org/dist/",
+    installPath: "/home/user/.oneagent/runtimes/node/v24.18.1",
+    requiredByHint: "Codex, Claude Code",
+    ...overrides,
+  };
+}
+
+describe("RuntimeSection", () => {
+  beforeEach(() => {
+    installRuntime.mockReset();
+  });
+
+  it("reports installed runtimes with their version and offers no install button", () => {
+    render(<RuntimeSection runtimes={[runtime({ installed: true, version: "24.18.1", managed: true })]} onInstalled={vi.fn()} />);
+    expect(screen.getByText("Node.js")).toBeTruthy();
+    expect(screen.getByText("版本 24.18.1")).toBeTruthy();
+    expect(screen.getByText("已安装")).toBeTruthy();
+    expect(screen.queryByRole("button", { name: "安装" })).toBeNull();
+  });
+
+  it("installs a missing runtime and refreshes status afterwards", async () => {
+    installRuntime.mockResolvedValue({ runtime: "node", installed: true, version: "24.18.1", pathUpdated: true, runtimes: [] });
+    const onInstalled = vi.fn();
+    render(<RuntimeSection runtimes={[runtime()]} onInstalled={onInstalled} />);
+    expect(screen.getByText("未安装")).toBeTruthy();
+
+    await userEvent.click(screen.getByRole("button", { name: "安装" }));
+    await waitFor(() => expect(onInstalled).toHaveBeenCalledTimes(1));
+    expect(installRuntime).toHaveBeenCalledWith("node");
+  });
+
+  it("surfaces an install failure without refreshing status", async () => {
+    installRuntime.mockImplementation(async () => {
+      throw new OneAgentApiError("校验和不匹配", "AGENT_INSTALL_FAILED", true, 400);
+    });
+    const onInstalled = vi.fn();
+    render(<RuntimeSection runtimes={[runtime()]} onInstalled={onInstalled} />);
+
+    await userEvent.click(screen.getByRole("button", { name: "安装" }));
+    await waitFor(() => expect(screen.getByText("校验和不匹配")).toBeTruthy());
+    expect(onInstalled).not.toHaveBeenCalled();
+  });
+
+  it("hides runtimes with no locked download for this platform", () => {
+    render(<RuntimeSection runtimes={[runtime({ supported: false })]} onInstalled={vi.fn()} />);
+    expect(screen.queryByText("Node.js")).toBeNull();
+  });
+});
+
+describe("RuntimePrompt", () => {
+  beforeEach(() => {
+    installRuntime.mockReset();
+  });
+
+  const agents = {
+    codex: { installed: false } as never,
+    opencode: { installed: true } as never,
+  };
+
+  it("prompts for the runtime a selected, not-yet-installed Agent needs", async () => {
+    installRuntime.mockResolvedValue({ runtime: "node", installed: true, version: "24.18.1", pathUpdated: true, runtimes: [] });
+    const onInstalled = vi.fn();
+    render(
+      <RuntimePrompt
+        runtimes={[runtime()]}
+        missingRuntime={{ codex: "node" }}
+        selectedAgentIds={["codex"]}
+        agents={agents}
+        onInstalled={onInstalled}
+      />,
+    );
+    expect(screen.getByText("需要先安装运行时")).toBeTruthy();
+
+    await userEvent.click(screen.getByRole("button", { name: "安装 Node.js 24.18.1" }));
+    await waitFor(() => expect(onInstalled).toHaveBeenCalledTimes(1));
+    expect(installRuntime).toHaveBeenCalledWith("node");
+  });
+
+  it("stays hidden when the only selected Agent is already installed", () => {
+    render(
+      <RuntimePrompt
+        runtimes={[runtime()]}
+        missingRuntime={{ codex: "node", opencode: "node" }}
+        selectedAgentIds={["opencode"]}
+        agents={agents}
+        onInstalled={vi.fn()}
+      />,
+    );
+    expect(screen.queryByText("需要先安装运行时")).toBeNull();
+  });
+
+  it("stays hidden once the runtime is present", () => {
+    render(
+      <RuntimePrompt
+        runtimes={[runtime({ installed: true, version: "22.0.0" })]}
+        missingRuntime={{ codex: "node" }}
+        selectedAgentIds={["codex"]}
+        agents={agents}
+        onInstalled={vi.fn()}
+      />,
+    );
+    expect(screen.queryByText("需要先安装运行时")).toBeNull();
+  });
+});
diff --git a/frontend/src/components/RuntimeSection.tsx b/frontend/src/components/RuntimeSection.tsx
new file mode 100644
index 00000000..5c8e436b
--- /dev/null
+++ b/frontend/src/components/RuntimeSection.tsx
@@ -0,0 +1,100 @@
+import { Boxes, Download, RefreshCw } from "lucide-react";
+import { useState } from "react";
+
+import { api, describeError } from "../backend/api";
+import { useI18n } from "../i18n";
+import type { RuntimeStatus } from "../types/api";
+import { StatusBadge } from "./StatusBadge";
+
+interface RuntimeSectionProps {
+  runtimes: RuntimeStatus[];
+  /** Called after a successful install so the caller can refresh status. */
+  onInstalled: () => void | Promise<void>;
+}
+
+export function RuntimeSection({ runtimes, onInstalled }: RuntimeSectionProps) {
+  const { t } = useI18n();
+  const [pending, setPending] = useState("");
+  const [failure, setFailure] = useState("");
+
+  const supported = runtimes.filter((runtime) => runtime.supported || runtime.installed);
+  if (!supported.length) return null;
+  const missing = supported.filter((runtime) => !runtime.installed);
+
+  const install = async (runtimeId: string) => {
+    setPending(runtimeId);
+    setFailure("");
+    try {
+      await api.installRuntime(runtimeId);
+      await onInstalled();
+    } catch (error) {
+      setFailure(describeError(error, t("运行时安装失败")).message);
+    } finally {
+      setPending("");
+    }
+  };
+
+  return (
+    <section className="overview-section">
+      <div className="section-heading">
+        <div>
+          <h2>{t("运行时")}</h2>
+          <p>
+            {missing.length
+              ? t("缺少 {count} 个运行时，安装后即可自动安装对应 Agent。", { count: missing.length })
+              : t("Agent 安装所需的运行时都已就绪。")}
+          </p>
+        </div>
+        <Boxes size={19} aria-hidden="true" />
+      </div>
+      {failure ? <div className="notice notice-error">{failure}</div> : null}
+      <div className="runtime-list">
+        {supported.map((runtime) => (
+          <div className="runtime-row" key={runtime.id}>
+            <span className="runtime-identity">
+              <strong>{runtime.name}</strong>
+              <small>
+                {runtime.installed
+                  ? runtime.version
+                    ? t("版本 {version}", { version: runtime.version })
+                    : t("版本未知")
+                  : runtime.requiredByHint
+                    ? t("{agents} 需要", { agents: runtime.requiredByHint })
+                    : t("待安装")}
+              </small>
+            </span>
+            <span className="runtime-fact">
+              <small>{t("锁定版本")}</small>
+              <span>{runtime.lockedVersion}</span>
+            </span>
+            <span className="runtime-fact">
+              <small>{t("来源")}</small>
+              <span>{runtime.managed ? t("由 OneAgent 安装") : runtime.installed ? t("本机已有") : runtime.source}</span>
+            </span>
+            <StatusBadge tone={runtime.installed ? "success" : "warning"}>
+              {runtime.installed ? t("已安装") : t("未安装")}
+            </StatusBadge>
+            {runtime.installed ? (
+              <span className="runtime-action-placeholder" aria-hidden="true" />
+            ) : (
+              <button
+                className="button button-secondary"
+                type="button"
+                onClick={() => void install(runtime.id)}
+                disabled={Boolean(pending)}
+              >
+                {pending === runtime.id ? <RefreshCw size={15} className="spin" /> : <Download size={15} />}
+                {pending === runtime.id ? t("安装中") : t("安装")}
+              </button>
+            )}
+          </div>
+        ))}
+      </div>
+      {missing.length ? (
+        <p className="runtime-note">
+          {t("运行时会安装到 ~/.oneagent/runtimes，并写入登录 PATH，不需要管理员权限。")}
+        </p>
+      ) : null}
+    </section>
+  );
+}
diff --git a/frontend/src/components/SecureKeyField.test.tsx b/frontend/src/components/SecureKeyField.test.tsx
index 364e4220..f79fd86a 100644
--- a/frontend/src/components/SecureKeyField.test.tsx
+++ b/frontend/src/components/SecureKeyField.test.tsx
@@ -25,4 +25,10 @@ describe("SecureKeyField", () => {
     await userEvent.click(screen.getByRole("button", { name: "隐藏密钥" }));
     expect(input).toHaveAttribute("type", "password");
   });
+
+  it("shows a key loaded after the field opens", () => {
+    const page = render(<SecureKeyField value="" onChange={() => {}} />);
+    page.rerender(<SecureKeyField value="sk-persisted" onChange={() => {}} />);
+    expect(screen.getByLabelText("API Key")).toHaveValue("sk-persisted");
+  });
 });
diff --git a/frontend/src/components/SecureKeyField.tsx b/frontend/src/components/SecureKeyField.tsx
index 3c14bdf8..5d589021 100644
--- a/frontend/src/components/SecureKeyField.tsx
+++ b/frontend/src/components/SecureKeyField.tsx
@@ -1,11 +1,15 @@
 import { Eye, EyeOff, KeyRound } from "lucide-react";
-import { useState } from "react";
+import { useEffect, useState } from "react";
+
+import { useI18n } from "../i18n";
 
 export function SecureKeyField({ value, onChange }: { value: string; onChange: (value: string) => void }) {
+  const { t } = useI18n();
   const [visible, setVisible] = useState(false);
   // The wizard keeps the key in a ref, not in state, so the parent gives no
   // re-render guarantee per keystroke; echo must come from local state.
   const [draft, setDraft] = useState(value);
+  useEffect(() => setDraft(value), [value]);
   return (
     <div className="field-stack">
       <label htmlFor="api-key">API Key</label>
@@ -21,13 +25,13 @@ export function SecureKeyField({ value, onChange }: { value: string; onChange: (
           }}
           autoComplete="off"
           spellCheck={false}
-          placeholder="粘贴你的 API Key"
+          placeholder={t("粘贴你的 API Key")}
         />
-        <button type="button" onClick={() => setVisible((current) => !current)} aria-label={visible ? "隐藏密钥" : "显示密钥"}>
+        <button type="button" onClick={() => setVisible((current) => !current)} aria-label={visible ? t("隐藏密钥") : t("显示密钥")}>
           {visible ? <EyeOff size={17} /> : <Eye size={17} />}
         </button>
       </div>
-      <small>密钥只发送到当前本机服务，并写入确认页列出的本地配置。</small>
+      <small>{t("密钥只发送到当前本机服务，并保存在本机私有配置中。")}</small>
     </div>
   );
 }
diff --git a/frontend/src/components/SetupStepper.tsx b/frontend/src/components/SetupStepper.tsx
index 2e404804..347c1033 100644
--- a/frontend/src/components/SetupStepper.tsx
+++ b/frontend/src/components/SetupStepper.tsx
@@ -1,12 +1,13 @@
 import { Check } from "lucide-react";
 import { useLocation } from "react-router-dom";
 
+import { type TranslationKey, useI18n } from "../i18n";
 import { useWizard } from "../state/WizardContext";
 
 // Single source of truth for the setup sequence: order, labels, and which
 // steps the existing-account mode skips. Pages no longer pass step numbers;
 // the current step is derived from the route.
-const steps = [
+const steps: Array<{ path: string; label: TranslationKey | "Agent" | "Provider"; skippedForExistingAccount: boolean }> = [
   { path: "/setup/agents", label: "Agent", skippedForExistingAccount: false },
   { path: "/setup/mode", label: "配置", skippedForExistingAccount: false },
   { path: "/setup/provider", label: "Provider", skippedForExistingAccount: true },
@@ -15,13 +16,14 @@ const steps = [
 ];
 
 export function SetupStepper() {
+  const { t } = useI18n();
   const { pathname } = useLocation();
   const { state } = useWizard();
   const skipsProvider = state.configMode === "existing-account";
   const current = steps.findIndex((step) => step.path === pathname) + 1;
 
   return (
-    <ol className="setup-stepper" aria-label="激活步骤">
+    <ol className="setup-stepper" aria-label={t("激活步骤")}>
       {steps.map((step, index) => {
         const number = index + 1;
         const skipped = skipsProvider && step.skippedForExistingAccount;
@@ -34,7 +36,7 @@ export function SetupStepper() {
             aria-current={active ? "step" : undefined}
           >
             <span className="stepper-marker">{complete ? <Check size={14} /> : number}</span>
-            <span className="stepper-label">{skipped ? "已跳过" : step.label}</span>
+            <span className="stepper-label">{skipped ? t("已跳过") : step.label === "Agent" || step.label === "Provider" ? step.label : t(step.label)}</span>
           </li>
         );
       })}
diff --git a/frontend/src/components/icons/agents.tsx b/frontend/src/components/icons/agents.tsx
index 35bdf864..2f3f4e3e 100644
--- a/frontend/src/components/icons/agents.tsx
+++ b/frontend/src/components/icons/agents.tsx
@@ -17,6 +17,8 @@
  */
 import { Bot } from "lucide-react";
 
+import { sourceTranslate, type Translate, type TranslationKey } from "../../i18n";
+
 import aiderMark from "./assets/aider.png";
 import claudeMark from "./assets/claude-code.svg";
 import codexMark from "./assets/codex.svg";
@@ -39,7 +41,7 @@ const MARKS: Record<string, { src: string; source: string }> = {
 };
 
 /** One-line positioning shown on hover; never a restatement of the name. */
-const TAGLINES: Record<string, string> = {
+const TAGLINES: Record<string, TranslationKey> = {
   codex: "OpenAI 的终端编码代理",
   "claude-code": "Anthropic 的终端编码代理",
   opencode: "开源终端编码代理",
@@ -52,8 +54,9 @@ const TAGLINES: Record<string, string> = {
 
 export const AGENT_ICON_IDS = Object.keys(MARKS);
 
-export function agentTagline(agentId: string): string {
-  return TAGLINES[agentId] ?? "";
+export function agentTagline(agentId: string, t: Translate = sourceTranslate): string {
+  const tagline = TAGLINES[agentId];
+  return tagline ? t(tagline) : "";
 }
 
 /** The provenance of an Agent's mark, for the reference notes and tests. */
diff --git a/frontend/src/i18n.test.tsx b/frontend/src/i18n.test.tsx
new file mode 100644
index 00000000..7beebeb2
--- /dev/null
+++ b/frontend/src/i18n.test.tsx
@@ -0,0 +1,21 @@
+import { act, renderHook } from "@testing-library/react";
+import type { PropsWithChildren } from "react";
+import { describe, expect, it } from "vitest";
+
+import { I18nProvider, LOCALE_STORAGE_KEY, translate, useI18n } from "./i18n";
+
+describe("i18n", () => {
+  it("translates placeholders and persists language changes", () => {
+    expect(translate("en", "已选择 {count} 个 Agent", { count: 2 })).toBe("Selected: 2");
+    localStorage.setItem(LOCALE_STORAGE_KEY, "en");
+    const wrapper = ({ children }: PropsWithChildren) => <I18nProvider>{children}</I18nProvider>;
+    const { result } = renderHook(() => useI18n(), { wrapper });
+
+    expect(result.current.t("返回")).toBe("Back");
+    expect(document.documentElement.lang).toBe("en");
+    act(() => result.current.setLocale("zh-CN"));
+    expect(result.current.t("返回")).toBe("返回");
+    expect(document.documentElement.lang).toBe("zh-CN");
+    expect(localStorage.getItem(LOCALE_STORAGE_KEY)).toBe("zh-CN");
+  });
+});
diff --git a/frontend/src/i18n.tsx b/frontend/src/i18n.tsx
new file mode 100644
index 00000000..ee01c8ba
--- /dev/null
+++ b/frontend/src/i18n.tsx
@@ -0,0 +1,316 @@
+import { createContext, type PropsWithChildren, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+
+const english = {
+  "Agent 管家": "Agent Manager",
+  "主导航": "Main navigation",
+  "工作区": "Workspace",
+  "激活环境": "Environment",
+  "配置模板": "Profiles",
+  "语言": "Language",
+  "返回": "Back",
+  "返回总览": "Back to overview",
+  "继续": "Continue",
+  "保存": "Save",
+  "保存中": "Saving",
+  "取消": "Cancel",
+  "关闭编辑": "Close editor",
+  "编辑": "Edit",
+  "删除": "Delete",
+  "名称": "Name",
+  "模型": "Model",
+  "版本": "Version",
+  "未知": "Unknown",
+  "暂无": "None",
+  "未记录": "Not recorded",
+  "未绑定": "Not linked",
+  "未安装": "Not installed",
+  "已安装": "Installed",
+  "待安装": "Not installed",
+  "仅引导": "Guide only",
+  "重试": "Retry",
+  "已完成": "Completed",
+  "失败": "Failed",
+  "正在处理": "Processing",
+  "等待执行": "Waiting",
+  "高级选项": "Advanced options",
+  "模型服务": "Provider",
+  "新增 Provider": "Add provider",
+  "搜索模型": "Search models",
+  "模型列表": "Model list",
+  "没有匹配的模型": "No matching models",
+  "或手动输入模型 ID": "Or enter a model ID",
+  "手动输入模型 ID": "Enter a model ID",
+  "例如 gpt-4.1": "For example, gpt-4.1",
+  "例如 deepseek/deepseek-v3": "For example, deepseek/deepseek-v3",
+  "例如 siliconflow": "For example, siliconflow",
+  "例如 team-ppio": "For example, team-ppio",
+  "例如 团队 PPIO": "For example, Team PPIO",
+  "粘贴你的 API Key": "Paste your API key",
+  "隐藏密钥": "Hide API key",
+  "显示密钥": "Show API key",
+  "密钥只发送到当前本机服务，并保存在本机私有配置中。": "The key is sent only to the local service and stored in private local configuration.",
+  "激活步骤": "Setup steps",
+  "配置": "Configure",
+  "确认": "Review",
+  "已跳过": "Skipped",
+  "尚未测试连接": "Connection not tested",
+  "正在验证端点和 Key": "Validating endpoint and key",
+  "连接失败": "Connection failed",
+  "查看安装日志": "View installation log",
+  "按官方方式安装与登录": "Install and sign in using the official method",
+  "已检测到": "Detected",
+  "官方安装": "Official install",
+  "官方文档": "Official docs",
+  "显示官方安装与配置步骤": "Show official installation and setup steps",
+  "支持检测、安装与初始化配置": "Supports detection, installation, and initial setup",
+  "选择 {name}": "Select {name}",
+  "配置无法解析": "Configuration could not be parsed",
+  "配置文件当前指向 {url}": "Configuration file currently points to {url}",
+  "检测到的配置，非 OneAgent 写入": "Detected configuration not written by OneAgent",
+  "未配置": "Not configured",
+  "{version}（锁定 {lockedVersion}）": "{version} (locked to {lockedVersion})",
+  "选择 Agent": "Select agents",
+  "选择要检测、安装或配置的开发工具，可以同时处理多个。": "Choose the development tools to detect, install, or configure. You can process several at once.",
+  "已选择 {count} 个 Agent": "Selected: {count}",
+  "至少选择一个 Agent": "Select at least one agent",
+  "正在检测本机环境": "Detecting the local environment",
+  "常用 Agent": "Popular agents",
+  "可一键配置的使用锁定版本完成初始化，仅引导的只显示官方步骤。": "One-click agents use locked versions for setup; guide-only agents show official steps.",
+  "更多 Agent（{count}）": "More agents ({count})",
+  "网关、平台账号与 IDE 扩展": "Gateways, platform accounts, and IDE extensions",
+  "安装缺失的 Agent": "Install missing agents",
+  "仅调用 lock manifest 中允许的官方 npm 或 uv 包。": "Uses only official npm or uv packages allowed by the lock manifest.",
+  "配置方式": "Setup method",
+  "选择由 OneAgent 初始化模型服务，或保留已有官方账号与本机配置。": "Let OneAgent configure a model provider, or keep existing accounts and local settings.",
+  "Provider 与模型步骤将标记为已跳过": "Provider and model steps will be marked as skipped",
+  "配置模型服务": "Configure a model provider",
+  "选择 PPIO、Novita 或自定义 OpenAI-compatible 服务。": "Choose PPIO, Novita, or a custom OpenAI-compatible service.",
+  "OneAgent 将测试连接、发现模型并写入本机配置。": "OneAgent will test the connection, discover models, and write local configuration.",
+  "使用已有账号或配置": "Use an existing account or configuration",
+  "只检测或安装 Agent，不写入第三方模型服务配置。": "Only detect or install agents without writing third-party provider settings.",
+  "适合已登录官方账号，或已经维护本机配置的用户。": "For users already signed in to official accounts or maintaining local configuration.",
+  "跳过配置不会删除或覆盖现有 Agent 设置。": "Skipping setup will not delete or overwrite existing agent settings.",
+  "无法读取已保存的 API Key": "Could not read the saved API key",
+  "连接测试失败": "Connection test failed",
+  "无法打开注册页面": "Could not open the registration page",
+  "连接模型服务": "Connect a model provider",
+  "Key 不会进入日志、URL 或前端持久化状态。": "The key is never written to logs, URLs, or persistent frontend state.",
+  "继续选择模型": "Continue to model selection",
+  "注册并获取 Key": "Register and get a key",
+  "自定义模型名称（可选）": "Custom model name (optional)",
+  "填写后将用此模型测试连接；留空时自动选择。": "When provided, this model is used for the connection test. Leave blank to select automatically.",
+  "测试连接": "Test connection",
+  "连接测试通过后才能继续选择模型。": "Pass the connection test before selecting a model.",
+  "无法获取模型列表": "Could not load the model list",
+  "选择模型": "Select a model",
+  "从当前 Key 可访问的模型中选择，接口不支持时可直接输入模型 ID。": "Choose a model accessible with this key, or enter a model ID when discovery is unavailable.",
+  "刷新列表": "Refresh list",
+  "正在读取模型列表": "Loading models",
+  "确认激活": "Review activation",
+  "核对安装、配置和备份范围。API Key 不会显示在此页。": "Review the installation, configuration, and backup scope. The API key is not shown here.",
+  "开始激活": "Start activation",
+  "覆盖前会自动创建时间戳备份": "A timestamped backup is created before overwrite",
+  "将处理": "Agents",
+  "检测并配置": "Detect and configure",
+  "安装并配置": "Install and configure",
+  "显示引导": "Show guide",
+  "只写配置": "Configure only",
+  "已有账号 / 本机配置": "Existing account / local configuration",
+  "本地写入": "Local changes",
+  "由 Agent 官方配置合约决定": "Defined by the agent's official configuration contract",
+  "模型配置": "Model configuration",
+  "跳过，不覆盖已有设置": "Skipped; existing settings are preserved",
+  "环境摘要": "Environment summary",
+  "仅引导项目": "Guide-only items",
+  "{count} 个，不写私有配置": "{count}; no private configuration written",
+  "激活失败": "Activation failed",
+  "重试失败": "Retry failed",
+  "正在激活": "Activating",
+  "激活完成": "Activation complete",
+  "需要处理部分问题": "Some items need attention",
+  "安装请求同步执行，完成后将显示每个 Agent 的最终状态。": "Installation runs synchronously. Each agent's final status appears when it completes.",
+  "每个 Agent 的结果彼此独立，失败项可以单独重试。": "Each agent has an independent result. Failed items can be retried individually.",
+  "进入总览": "Open overview",
+  "请保持此窗口打开": "Keep this window open",
+  "下一步命令": "Next command",
+  "环境总览": "Environment overview",
+  "正在读取环境状态": "Loading environment status",
+  "本机已安装 Agent 及其当前配置。": "Installed agents and their current local configuration.",
+  "无法读取环境状态": "Could not load environment status",
+  "请刷新后重试。": "Refresh and try again.",
+  "本机已安装 Agent 及其当前 Provider、Profile 与模型。": "Installed agents and their current providers, profiles, and models.",
+  "刷新状态": "Refresh status",
+  "已安装 Agent": "Installed agents",
+  "共 {count} 个": "Total: {count}",
+  "尚未安装任何 Agent": "No agents installed",
+  "运行时": "Runtimes",
+  "缺少 {count} 个运行时，安装后即可自动安装对应 Agent。": "{count} runtime(s) missing. Install them to enable automatic agent installation.",
+  "Agent 安装所需的运行时都已就绪。": "Every runtime needed to install agents is ready.",
+  "运行时安装失败": "Could not install the runtime",
+  "版本 {version}": "Version {version}",
+  "版本未知": "Version unknown",
+  "{agents} 需要": "Required by {agents}",
+  "锁定版本": "Locked version",
+  "来源": "Source",
+  "由 OneAgent 安装": "Installed by OneAgent",
+  "本机已有": "Already on this machine",
+  "安装": "Install",
+  "安装中": "Installing",
+  "运行时会安装到 ~/.oneagent/runtimes，并写入登录 PATH，不需要管理员权限。": "Runtimes install into ~/.oneagent/runtimes and are added to your login PATH. No administrator rights needed.",
+  "需要先安装运行时": "A runtime is needed first",
+  "所选 Agent 通过 {runtimes} 安装，本机还没有。现在安装，或在激活时自动安装。": "The selected agents install through {runtimes}, which is not on this machine yet. Install it now, or let activation install it.",
+  "安装 {name} {version}": "Install {name} {version}",
+  "在配置模板中创建 Profile 并应用后，已安装的 Agent 会显示在这里。": "Create and apply a profile to see installed agents here.",
+  "找不到可配置的 Agent": "Configurable agent not found",
+  "{id} 不在可一键配置的范围内。": "{id} is not available for one-click setup.",
+  "未指定 Agent。": "No agent specified.",
+  "应用配置失败": "Could not apply configuration",
+  "应用中": "Applying",
+  "应用": "Apply",
+  "当前指向": "Current target",
+  "配置文件": "Configuration file",
+  "备份": "Backups",
+  "已有历史备份": "Previous backup available",
+  "这个 Agent 已有配置，不是 OneAgent 写入的": "This agent has configuration not written by OneAgent",
+  "未知端点": "Unknown endpoint",
+  "当前指向 {target}。应用后会被替换，原文件会先备份到同目录的": "Currently points to {target}. Applying will replace it; the original file will first be backed up in the same directory as",
+  "时间戳": "timestamp",
+  "将测试 {protocol} 协议": "Testing the {protocol} protocol",
+  "可以指定具体模型。留空时由端点的模型列表自动选择，多数情况保持默认即可。": "Optionally choose a specific model. Leave blank for endpoint discovery; the default works in most cases.",
+  "留空则由端点的模型列表自动选择": "Leave blank to select from the endpoint's model list",
+  "快速小模型": "Fast small model",
+  "留空则与主模型相同": "Leave blank to use the primary model",
+  "已写入配置": "Configuration written",
+  "无法读取 Provider": "Could not load provider",
+  "无法保存 Provider": "Could not save provider",
+  "删除 Provider“{name}”？": "Delete provider \"{name}\"?",
+  "无法删除 Provider": "Could not delete provider",
+  "管理模型服务、端点与本机保存的 API Key。": "Manage model providers, endpoints, and locally saved API keys.",
+  "编辑 {name}": "Edit {name}",
+  "用户添加": "User added",
+  "官网": "Website",
+  "官网（可选）": "Website (optional)",
+  "OpenAI 兼容 Base URL": "OpenAI-compatible base URL",
+  "Anthropic 兼容 Base URL（可选）": "Anthropic-compatible base URL (optional)",
+  "OpenAI 兼容": "OpenAI-compatible",
+  "Anthropic 兼容": "Anthropic-compatible",
+  "删除 {name}": "Delete {name}",
+  "暂无 Agent 使用": "Not used by any agent",
+  "已保存 Key": "Key saved",
+  "未保存 Key": "No saved key",
+  "用户 Provider 的协议兼容性由你自己保证，OneAgent 不会为它降级或改写请求。": "You are responsible for custom provider protocol compatibility. OneAgent does not downgrade or rewrite requests.",
+  "无法保存 Profile": "Could not save profile",
+  "应用 Profile 失败": "Could not apply profile",
+  "{name} 已应用到 {count} 个 Agent": "Applied {name} to {count} agents",
+  "无法应用 Profile": "Could not apply profile",
+  "在这里创建 Profile，再将它应用到所选 Agent。": "Create profiles here, then apply them to selected agents.",
+  "新增 Profile": "Add profile",
+  "留空将保留这个 Profile 已保存的 Key。": "Leave blank to keep this profile's saved key.",
+  "留空将使用 Provider 已保存的 Key。": "Leave blank to use the provider's saved key.",
+  "适用 Agent": "Agents",
+  "保存 Profile": "Save profile",
+  "应用完成": "Applied",
+  "还没有 Profile": "No profiles yet",
+  "新建一个 Profile，保存 Provider、模型、Key 和适用 Agent。": "Create a profile to save a provider, model, key, and agents.",
+  "已保存密钥": "Key saved",
+  "未保存密钥": "No saved key",
+  "未指定模型": "No model specified",
+  "未选择 Agent": "No agents selected",
+  "适用：{agents}": "Agents: {agents}",
+  "安装缺失的 Agent 并应用此 Profile": "Install missing agents and apply this profile",
+  "请先补全模型、Agent 和 Key": "Add a model, agents, and key first",
+  "应用到 Agent": "Apply to agents",
+  "无法读取本机状态": "Could not read local status",
+  "OneAgent 请求失败": "OneAgent request failed",
+  "无法调用本机 OneAgent 服务": "Could not call the local OneAgent service",
+  "OpenAI 的终端编码代理": "OpenAI's terminal coding agent",
+  "Anthropic 的终端编码代理": "Anthropic's terminal coding agent",
+  "开源终端编码代理": "Open-source terminal coding agent",
+  "多模型编排的命令行代理": "Command-line agent with multi-model orchestration",
+  "结对编程式的仓库编辑代理": "Pair-programming repository editing agent",
+  "AI 编辑器，按官方方式安装": "AI editor installed through the official channel",
+  "多渠道 AI 网关，常驻运行": "Persistent multi-channel AI gateway",
+  "自我成长型 Agent 框架": "Self-improving agent framework",
+} as const;
+
+export type Locale = "zh-CN" | "en";
+export type TranslationKey = keyof typeof english;
+export type TranslationValues = Record<string, string | number>;
+export type Translate = (key: TranslationKey, values?: TranslationValues) => string;
+
+export const LOCALE_STORAGE_KEY = "oneagent.locale";
+
+function interpolate(template: string, values: TranslationValues = {}): string {
+  return template.replace(/\{(\w+)\}/g, (placeholder, name: string) =>
+    Object.hasOwn(values, name) ? String(values[name]) : placeholder,
+  );
+}
+
+export function translate(locale: Locale, key: TranslationKey, values?: TranslationValues): string {
+  return interpolate(locale === "en" ? english[key] : key, values);
+}
+
+export const sourceTranslate: Translate = (key, values) => translate("zh-CN", key, values);
+
+function preferredLocale(): Locale {
+  try {
+    const saved = localStorage.getItem(LOCALE_STORAGE_KEY);
+    if (saved === "en" || saved === "zh-CN") return saved;
+  } catch {
+    // Storage can be unavailable in hardened webviews; system language still works.
+  }
+  return typeof navigator !== "undefined" && !navigator.language.toLowerCase().startsWith("zh") ? "en" : "zh-CN";
+}
+
+let activeLocale: Locale | undefined;
+
+export function currentLocale(): Locale {
+  try {
+    const saved = localStorage.getItem(LOCALE_STORAGE_KEY);
+    if (saved === "en" || saved === "zh-CN") return saved;
+  } catch {
+    // Fall through to the active provider or system language.
+  }
+  return activeLocale ?? preferredLocale();
+}
+
+interface I18nContextValue {
+  locale: Locale;
+  setLocale: (locale: Locale) => void;
+  t: Translate;
+}
+
+const fallback: I18nContextValue = {
+  locale: "zh-CN",
+  setLocale: () => undefined,
+  t: sourceTranslate,
+};
+
+const I18nContext = createContext<I18nContextValue>(fallback);
+
+export function I18nProvider({ children }: PropsWithChildren) {
+  const [locale, setLocaleState] = useState<Locale>(preferredLocale);
+  const localeRef = useRef(locale);
+  localeRef.current = locale;
+  activeLocale = locale;
+  const setLocale = useCallback((next: Locale) => {
+    setLocaleState(next);
+    try {
+      localStorage.setItem(LOCALE_STORAGE_KEY, next);
+    } catch {
+      // The in-memory choice remains active when persistence is unavailable.
+    }
+  }, []);
+  const t = useCallback<Translate>((key, values) => translate(localeRef.current, key, values), []);
+
+  useEffect(() => {
+    document.documentElement.lang = locale;
+  }, [locale]);
+
+  const value = useMemo(() => ({ locale, setLocale, t }), [locale, setLocale, t]);
+  return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>;
+}
+
+export function useI18n(): I18nContextValue {
+  return useContext(I18nContext);
+}
diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx
index 93404e46..f74ca0c2 100644
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@@ -6,7 +6,6 @@ import App from "./App";
 import "./styles/tokens.css";
 import "./styles/base.css";
 import "./styles/app.css";
-import "./styles/landing.css";
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
diff --git a/frontend/src/pages/ActivationPage.tsx b/frontend/src/pages/ActivationPage.tsx
index d2336b6b..3dd43135 100644
--- a/frontend/src/pages/ActivationPage.tsx
+++ b/frontend/src/pages/ActivationPage.tsx
@@ -1,15 +1,17 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useNavigate } from "react-router-dom";
 
-import { api, describeError } from "../api/client";
+import { api, describeError } from "../backend/api";
 import { AgentProgressRow } from "../components/AgentProgressRow";
 import { LogDisclosure } from "../components/LogDisclosure";
 import { PageScaffold } from "../components/PageScaffold";
+import { useI18n } from "../i18n";
 import { useWizard } from "../state/WizardContext";
 import type { InstallRequest } from "../types/api";
 
 export function ActivationPage() {
   const navigate = useNavigate();
+  const { t } = useI18n();
   const { state, dispatch, secret, refreshStatus } = useWizard();
   const started = useRef(false);
   const [retrying, setRetrying] = useState<string | null>(null);
@@ -23,7 +25,7 @@ export function ActivationPage() {
       agents,
       profile_agents: profileAgents,
       provider: state.provider,
-      api_base_url: state.provider === "custom" ? state.customBaseUrl : "",
+      api_base_url: "",
       api_key: state.configMode === "provider" ? secret.keyRef.current : "",
       // SetupGuard guarantees a model in provider mode; existing-account mode
       // sends none and the backend does not write model config for it.
@@ -33,7 +35,7 @@ export function ActivationPage() {
       skip_test: state.configMode !== "provider",
       locked_version: true,
     }),
-    [secret.keyRef, state.configMode, state.customBaseUrl, state.installMissingAgents, state.model, state.provider],
+    [secret.keyRef, state.configMode, state.installMissingAgents, state.model, state.provider],
   );
 
   const activate = useCallback(async () => {
@@ -53,9 +55,11 @@ export function ActivationPage() {
         await refreshStatus();
       }
     } catch (error) {
-      dispatch({ type: "ACTIVATION_FAILED", message: describeError(error, "激活失败").message });
+      dispatch({ type: "ACTIVATION_FAILED", message: describeError(error, t("激活失败")).message });
     }
-  }, [dispatch, refreshStatus, requestFor, secret, state.selectedAgentIds]);
+  }, [dispatch, refreshStatus, requestFor, secret, state.selectedAgentIds, t]);
+
+  useEffect(() => api.onInstallOutput((output) => dispatch({ type: "ACTIVATION_OUTPUT", output })), [dispatch]);
 
   useEffect(() => {
     // Runs only for an explicit request from the review page. Returning here
@@ -85,7 +89,7 @@ export function ActivationPage() {
         await refreshStatus();
       }
     } catch (error) {
-      dispatch({ type: "ACTIVATION_FAILED", message: describeError(error, "重试失败").message });
+      dispatch({ type: "ACTIVATION_FAILED", message: describeError(error, t("重试失败")).message });
     } finally {
       setRetrying(null);
     }
@@ -94,12 +98,12 @@ export function ActivationPage() {
   const allDone = state.activationState === "success";
   return (
     <PageScaffold
-      title={state.activationState === "loading" ? "正在激活" : allDone ? "激活完成" : "需要处理部分问题"}
-      description={state.activationState === "loading" ? "安装请求同步执行，完成后将显示每个 Agent 的最终状态。" : "每个 Agent 的结果彼此独立，失败项可以单独重试。"}
+      title={state.activationState === "loading" ? t("正在激活") : allDone ? t("激活完成") : t("需要处理部分问题")}
+      description={state.activationState === "loading" ? t("安装请求同步执行，完成后将显示每个 Agent 的最终状态。") : t("每个 Agent 的结果彼此独立，失败项可以单独重试。")}
       onBack={state.activationState === "loading" ? undefined : () => navigate("/setup/review")}
-      primaryLabel={allDone ? "进入总览" : undefined}
+      primaryLabel={allDone ? t("进入总览") : undefined}
       onPrimary={allDone ? () => navigate("/overview") : undefined}
-      footerNote={state.activationState === "loading" ? "请保持此窗口打开" : undefined}
+      footerNote={state.activationState === "loading" ? t("请保持此窗口打开") : undefined}
     >
       <div className="progress-list">
         {state.selectedAgentIds.map((agentId) => {
@@ -122,11 +126,11 @@ export function ActivationPage() {
           the overview a user opens every day. */}
       {allDone && state.activationNext ? (
         <section className="next-command-section">
-          <h2>下一步命令</h2>
+          <h2>{t("下一步命令")}</h2>
           <pre>{state.activationNext}</pre>
         </section>
       ) : null}
-      <LogDisclosure log={state.activationLog} />
+      <LogDisclosure log={state.activationLog} open={state.activationState === "loading" || retrying !== null} />
     </PageScaffold>
   );
 }
diff --git a/frontend/src/pages/AgentDetailPage.test.tsx b/frontend/src/pages/AgentDetailPage.test.tsx
index 9dcc14e0..ab7d65d5 100644
--- a/frontend/src/pages/AgentDetailPage.test.tsx
+++ b/frontend/src/pages/AgentDetailPage.test.tsx
@@ -2,6 +2,7 @@ import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { MemoryRouter, Route, Routes } from "react-router-dom";
 import { describe, expect, it, vi } from "vitest";
 
+import { api } from "../backend/api";
 import type { StatusResponse } from "../types/api";
 import { AgentDetailPage } from "./AgentDetailPage";
 
@@ -15,7 +16,8 @@ function status(): StatusResponse {
   return {
     apiVersion: 1,
     platform: { os: "macos", arch: "arm64", shell: "bash" },
-    capabilities: { canInstall: { codex: true }, supportedAgentIds: ["codex"] },
+    runtimes: [],
+    capabilities: { canInstall: { codex: true }, missingRuntime: {}, supportedAgentIds: ["codex"] },
     agents: {
       codex: {
         installed: true,
@@ -26,6 +28,7 @@ function status(): StatusResponse {
         lockedVersion: "0.145.0",
         canInstall: true,
         provider: "ppio",
+        profileId: null,
         model: "deepseek/deepseek-v3",
         baseUrl: "https://api.ppio.com/openai",
         updatedAt: "2026-07-27T00:00:00Z",
@@ -62,7 +65,8 @@ function claudeStatus(): StatusResponse {
   const base = status();
   return {
     ...base,
-    capabilities: { canInstall: { "claude-code": true }, supportedAgentIds: ["claude-code"] },
+    runtimes: [],
+    capabilities: { canInstall: { "claude-code": true }, missingRuntime: {}, supportedAgentIds: ["claude-code"] },
     agents: {
       "claude-code": {
         installed: true,
@@ -73,6 +77,7 @@ function claudeStatus(): StatusResponse {
         lockedVersion: "2.1.217",
         canInstall: true,
         provider: "ppio",
+        profileId: null,
         model: "model-a",
         baseUrl: "https://api.ppio.com/anthropic",
         updatedAt: "2026-07-27T00:00:00Z",
@@ -104,6 +109,7 @@ function renderPage(agentId = "codex", override?: StatusResponse) {
     <MemoryRouter initialEntries={[`/agents/${agentId}`]}>
       <Routes>
         <Route path="/agents/:agentId" element={<AgentDetailPage />} />
+        <Route path="/providers/new" element={<div>新增页占位</div>} />
         <Route path="/overview" element={<div>总览占位</div>} />
       </Routes>
     </MemoryRouter>,
@@ -129,9 +135,22 @@ describe("AgentDetailPage", () => {
     expect(screen.getByRole("button", { name: /^应用/ }).hasAttribute("disabled")).toBe(true);
   });
 
+  it("offers user Providers in the configuration menu", () => {
+    const withUserProvider = status();
+    withUserProvider.providers.acme = { name: "Acme", home: "", base_url: "https://api.acme.test", custom: true };
+    renderPage("codex", withUserProvider);
+    expect(screen.getByRole("option", { name: "Acme" })).toBeTruthy();
+    expect(screen.queryByRole("option", { name: "自定义端点" })).toBeNull();
+  });
+
+  it("opens the Provider creation page from the picker", () => {
+    renderPage();
+    fireEvent.click(screen.getByRole("button", { name: "新增 Provider" }));
+    expect(screen.getByText("新增页占位")).toBeTruthy();
+  });
+
   it("drops a passing verdict when the key is edited afterwards", async () => {
     // Constraint 2: otherwise a wrong key rides in on the previous verdict.
-    const { api } = await import("../api/client");
     vi.spyOn(api, "probe").mockResolvedValue(passingProbe());
     renderPage();
     fireEvent.change(screen.getByLabelText(/API Key/i), { target: { value: "sk-good" } });
@@ -147,7 +166,6 @@ describe("AgentDetailPage", () => {
   it("reports the restart instruction and clears the key after applying", async () => {
     // Constraints 3 and 4: an Agent reads its config at startup, so silence
     // reads as failure; and a key left in a visible field outlives its request.
-    const { api } = await import("../api/client");
     vi.spyOn(api, "probe").mockResolvedValue(passingProbe());
     vi.spyOn(api, "activateAgent").mockResolvedValue({
       ok: true,
@@ -201,7 +219,6 @@ describe("AgentDetailPage", () => {
   it("offers Claude Code a fast small-model field and sends it on activate", async () => {
     // The one user-facing difference between adapters: Claude Code runs its
     // background work on a second, optionally cheaper model.
-    const { api } = await import("../api/client");
     vi.spyOn(api, "probe").mockResolvedValue(passingProbe());
     const activate = vi.spyOn(api, "activateAgent").mockResolvedValue({
       ok: true,
@@ -267,4 +284,15 @@ describe("AgentDetailPage", () => {
     renderPage("codex", ours);
     expect(screen.queryByText(/不是 OneAgent 写入/)).toBeNull();
   });
+
+  it("shows the Provider key again when the page is reopened", async () => {
+    const saved = status();
+    saved.providers.ppio.has_key = true;
+    vi.spyOn(api, "getProvider").mockResolvedValue({
+      id: "ppio", name: "PPIO", home: "https://ppio.com/", base_url: "https://api.ppio.com/openai",
+      anthropic_base_url: "https://api.ppio.com/anthropic", api_key: "sk-persisted", built_in: true,
+    });
+    renderPage("codex", saved);
+    await waitFor(() => expect(screen.getByLabelText(/API Key/i)).toHaveValue("sk-persisted"));
+  });
 });
diff --git a/frontend/src/pages/AgentDetailPage.tsx b/frontend/src/pages/AgentDetailPage.tsx
index 0c4d4abe..a17a8dc8 100644
--- a/frontend/src/pages/AgentDetailPage.tsx
+++ b/frontend/src/pages/AgentDetailPage.tsx
@@ -1,8 +1,8 @@
 import { FlaskConical } from "lucide-react";
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { useNavigate, useParams, useSearchParams } from "react-router-dom";
 
-import { api, describeError } from "../api/client";
+import { api, describeError } from "../backend/api";
 import { AdvancedSection } from "../components/AdvancedSection";
 import { ConnectionStatus } from "../components/ConnectionStatus";
 import { AgentIcon, agentTagline } from "../components/icons/agents";
@@ -10,6 +10,7 @@ import { PageScaffold } from "../components/PageScaffold";
 import { ProviderSegment } from "../components/ProviderSegment";
 import { SecureKeyField } from "../components/SecureKeyField";
 import { targetSummary, versionNote } from "../components/AgentManageRow";
+import { useI18n } from "../i18n";
 import { useWizard } from "../state/WizardContext";
 import { PROTOCOL_LABELS } from "../types/api";
 import type { ProbeResponse, ProviderId } from "../types/api";
@@ -18,13 +19,14 @@ export function AgentDetailPage() {
   const { agentId = "" } = useParams();
   const [params] = useSearchParams();
   const navigate = useNavigate();
+  const { locale, t } = useI18n();
   const { state, refreshStatus } = useWizard();
   const status = state.status;
   const agent = status?.agents[agentId];
   const catalog = status?.catalog.find((item) => item.id === agentId);
 
-  const [provider, setProvider] = useState<ProviderId>((agent?.provider as ProviderId) || "ppio");
-  const [customBaseUrl, setCustomBaseUrl] = useState(agent?.provider === "custom" ? agent.baseUrl || "" : "");
+  const initialProvider = agent?.provider && status?.providers[agent.provider] ? agent.provider : "ppio";
+  const [provider, setProvider] = useState<ProviderId>(initialProvider);
   const [apiKey, setApiKey] = useState("");
   const [model, setModel] = useState(agent?.model || "");
   const [smallFastModel, setSmallFastModel] = useState("");
@@ -37,23 +39,36 @@ export function AgentDetailPage() {
   // cannot clear the field; remounting it does.
   const [keyFieldId, setKeyFieldId] = useState(0);
 
+  useEffect(() => {
+    if (!status?.providers[provider]?.has_key) return;
+    let active = true;
+    void api.getProvider(provider)
+      .then((entry) => {
+        if (active) setApiKey(entry.api_key);
+      })
+      .catch((error) => {
+        if (active) setFailure(describeError(error, t("无法读取已保存的 API Key")).message);
+      });
+    return () => { active = false; };
+  }, [provider, status?.providers]);
+
   if (!status || !agent || !catalog || catalog.configMode !== "auto") {
     return (
       <PageScaffold
         title="Agent"
-        primaryLabel="返回总览"
+        primaryLabel={t("返回总览")}
         onPrimary={() => navigate("/overview")}
       >
         <div className="empty-overview">
-          <strong>找不到可配置的 Agent</strong>
-          <span>{agentId ? `${agentId} 不在可一键配置的范围内。` : "未指定 Agent。"}</span>
+          <strong>{t("找不到可配置的 Agent")}</strong>
+          <span>{agentId ? t("{id} 不在可一键配置的范围内。", { id: agentId }) : t("未指定 Agent。")}</span>
         </div>
       </PageScaffold>
     );
   }
 
-  const version = versionNote(agent);
-  const target = targetSummary(agent, status.providers);
+  const version = versionNote(agent, t);
+  const target = targetSummary(agent, status.providers, t);
   // A configuration OneAgent did not write is the case worth warning about:
   // applying replaces it, and the user may not know it is there. A backup is
   // taken either way, but saying so beforehand is the point.
@@ -61,7 +76,7 @@ export function AgentDetailPage() {
     agent.detected && !agent.detected.managedByOneAgent && !agent.detected.unreadable
       ? agent.detected
       : null;
-  const canProbe = Boolean(apiKey) && (provider !== "custom" || Boolean(customBaseUrl.trim()));
+  const canProbe = Boolean(apiKey);
   const canApply = canProbe && probeState === "success" && !applying;
 
   const resetVerdict = () => {
@@ -77,7 +92,7 @@ export function AgentDetailPage() {
     try {
       const result = await api.probe({
         provider,
-        apiBaseUrl: provider === "custom" ? customBaseUrl : "",
+        apiBaseUrl: "",
         apiKey,
         model,
         agents: [agentId],
@@ -86,7 +101,7 @@ export function AgentDetailPage() {
       setProbeState(result.ok ? "success" : "error");
     } catch (error) {
       setProbeState("error");
-      setFailure(describeError(error, "连接测试失败").message);
+      setFailure(describeError(error, t("连接测试失败")).message);
     }
   };
 
@@ -96,7 +111,7 @@ export function AgentDetailPage() {
     try {
       const result = await api.activateAgent(agentId, {
         provider,
-        apiBaseUrl: provider === "custom" ? customBaseUrl : "",
+        apiBaseUrl: "",
         apiKey,
         model,
         profileId: params.get("profile") || undefined,
@@ -109,7 +124,7 @@ export function AgentDetailPage() {
       setProbe(null);
       void refreshStatus();
     } catch (error) {
-      setFailure(describeError(error, "应用配置失败").message);
+      setFailure(describeError(error, t("应用配置失败")).message);
     } finally {
       setApplying(false);
     }
@@ -118,10 +133,10 @@ export function AgentDetailPage() {
   return (
     <PageScaffold
       title={catalog.name}
-      description={agentTagline(agentId) || undefined}
-      backLabel="返回总览"
+      description={agentTagline(agentId, t) || undefined}
+      backLabel={t("返回总览")}
       onBack={() => navigate("/overview")}
-      primaryLabel={applying ? "应用中" : "应用"}
+      primaryLabel={applying ? t("应用中") : t("应用")}
       onPrimary={() => void apply()}
       primaryDisabled={!canApply}
     >
@@ -131,23 +146,23 @@ export function AgentDetailPage() {
         </span>
         <dl className="detail-facts">
           <div>
-            <dt>当前指向</dt>
+            <dt>{t("当前指向")}</dt>
             <dd>
               {target.text}
               {target.note ? <small className="detail-drift">{target.note}</small> : null}
             </dd>
           </div>
           <div>
-            <dt>版本</dt>
-            <dd className={version?.behind ? "is-behind" : ""}>{version?.text || "未安装"}</dd>
+            <dt>{t("版本")}</dt>
+            <dd className={version?.behind ? "is-behind" : ""}>{version?.text || t("未安装")}</dd>
           </div>
           <div>
-            <dt>配置文件</dt>
+            <dt>{t("配置文件")}</dt>
             <dd>{agent.config || "—"}</dd>
           </div>
           <div>
-            <dt>备份</dt>
-            <dd>{status.backups[agentId] ? "已有历史备份" : "暂无"}</dd>
+            <dt>{t("备份")}</dt>
+            <dd>{status.backups[agentId] ? t("已有历史备份") : t("暂无")}</dd>
           </div>
         </dl>
       </div>
@@ -155,38 +170,26 @@ export function AgentDetailPage() {
       <section className="detail-form">
         {willOverwrite ? (
           <div className="notice notice-warning">
-            <strong>这个 Agent 已有配置，不是 OneAgent 写入的</strong>
+            <strong>{t("这个 Agent 已有配置，不是 OneAgent 写入的")}</strong>
             <span>
-              当前指向 {willOverwrite.baseUrl || "未知端点"}
-              {willOverwrite.model ? ` · ${willOverwrite.model}` : ""}。应用后会被替换，原文件会先备份到同目录的
+              {t("当前指向 {target}。应用后会被替换，原文件会先备份到同目录的", {
+                target: [willOverwrite.baseUrl || t("未知端点"), willOverwrite.model].filter(Boolean).join(" · "),
+              })}
               {" "}
-              <code>*.backup-&lt;时间戳&gt;</code>。
+              <code>*.backup-&lt;{t("时间戳")}&gt;</code>{locale === "en" ? "." : "。"}
             </span>
           </div>
         ) : null}
         <ProviderSegment
           value={provider}
+          providers={status.providers}
+          onAdd={() => navigate(`/providers/new?returnTo=${encodeURIComponent(`/agents/${agentId}`)}`)}
           onChange={(next) => {
             setProvider(next);
+            setApiKey("");
             resetVerdict();
           }}
         />
-        {provider === "custom" ? (
-          <div className="field-stack">
-            <label htmlFor="detail-base-url">Base URL</label>
-            <input
-              id="detail-base-url"
-              className="text-field"
-              value={customBaseUrl}
-              onChange={(event) => {
-                setCustomBaseUrl(event.target.value);
-                resetVerdict();
-              }}
-              placeholder="https://models.example.com/openai"
-              inputMode="url"
-            />
-          </div>
-        ) : null}
         <SecureKeyField
           key={keyFieldId}
           value={apiKey}
@@ -204,17 +207,17 @@ export function AgentDetailPage() {
             disabled={!canProbe || probeState === "loading"}
           >
             <FlaskConical size={16} />
-            测试连接
+            {t("测试连接")}
           </button>
           <ConnectionStatus state={probeState} result={probe} />
         </div>
         {catalog.protocol ? (
-          <small className="detail-protocol">将测试 {PROTOCOL_LABELS[catalog.protocol]} 协议</small>
+          <small className="detail-protocol">{t("将测试 {protocol} 协议", { protocol: PROTOCOL_LABELS[catalog.protocol] })}</small>
         ) : null}
 
-        <AdvancedSection hint="可以指定具体模型。留空时由端点的模型列表自动选择，多数情况保持默认即可。">
+        <AdvancedSection hint={t("可以指定具体模型。留空时由端点的模型列表自动选择，多数情况保持默认即可。")}>
           <div className="field-stack">
-            <label htmlFor="detail-model">模型</label>
+            <label htmlFor="detail-model">{t("模型")}</label>
             <input
               id="detail-model"
               className="text-field"
@@ -223,18 +226,18 @@ export function AgentDetailPage() {
                 setModel(event.target.value);
                 resetVerdict();
               }}
-              placeholder="留空则由端点的模型列表自动选择"
+              placeholder={t("留空则由端点的模型列表自动选择")}
             />
           </div>
           {agentId === "claude-code" ? (
             <div className="field-stack">
-              <label htmlFor="detail-small-fast-model">快速小模型</label>
+              <label htmlFor="detail-small-fast-model">{t("快速小模型")}</label>
               <input
                 id="detail-small-fast-model"
                 className="text-field"
                 value={smallFastModel}
                 onChange={(event) => setSmallFastModel(event.target.value)}
-                placeholder="留空则与主模型相同"
+                placeholder={t("留空则与主模型相同")}
               />
             </div>
           ) : null}
@@ -243,7 +246,7 @@ export function AgentDetailPage() {
         {failure ? <p className="agent-manage-error">{failure}</p> : null}
         {applied ? (
           <div className="agent-manage-applied">
-            <strong>已写入配置</strong>
+            <strong>{t("已写入配置")}</strong>
             <span>{applied.restart}</span>
             {applied.next ? <pre>{applied.next}</pre> : null}
           </div>
diff --git a/frontend/src/pages/AgentSelectionPage.test.tsx b/frontend/src/pages/AgentSelectionPage.test.tsx
index 1986ca58..f79087e8 100644
--- a/frontend/src/pages/AgentSelectionPage.test.tsx
+++ b/frontend/src/pages/AgentSelectionPage.test.tsx
@@ -42,7 +42,8 @@ function renderPage() {
     status: {
       apiVersion: 1,
       platform: { os: "macos", arch: "arm64", shell: "bash" },
-      capabilities: { canInstall: {}, supportedAgentIds: [] },
+      runtimes: [],
+      capabilities: { canInstall: {}, missingRuntime: {}, supportedAgentIds: [] },
       agents: Object.fromEntries(
         CATALOG.map((item) => [
           item.id,
@@ -55,6 +56,7 @@ function renderPage() {
             lockedVersion: item.lockedVersion,
             canInstall: !item.guideOnly,
             provider: null,
+            profileId: null,
             model: null,
             baseUrl: null,
             updatedAt: null,
diff --git a/frontend/src/pages/AgentSelectionPage.tsx b/frontend/src/pages/AgentSelectionPage.tsx
index d9b3d960..a81f2115 100644
--- a/frontend/src/pages/AgentSelectionPage.tsx
+++ b/frontend/src/pages/AgentSelectionPage.tsx
@@ -4,13 +4,16 @@ import { useNavigate } from "react-router-dom";
 
 import { AgentRow } from "../components/AgentRow";
 import { PageScaffold } from "../components/PageScaffold";
+import { RuntimePrompt } from "../components/RuntimePrompt";
+import { useI18n } from "../i18n";
 import { splitByRank } from "../state/ranking";
 import type { AgentCatalogItem } from "../types/api";
 import { useWizard } from "../state/WizardContext";
 
 export function AgentSelectionPage() {
   const navigate = useNavigate();
-  const { state, dispatch } = useWizard();
+  const { t } = useI18n();
+  const { state, dispatch, refreshStatus } = useWizard();
   const [showMore, setShowMore] = useState(false);
   // Ranked, not grouped by catalog group. Leading with the "auto" group put Kilo
   // and Aider on the first screen and folded Cursor, OpenClaw and Hermes away.
@@ -34,24 +37,24 @@ export function AgentSelectionPage() {
 
   return (
     <PageScaffold
-      title="选择 Agent"
-      description="选择要检测、安装或配置的开发工具，可以同时处理多个。"
+      title={t("选择 Agent")}
+      description={t("选择要检测、安装或配置的开发工具，可以同时处理多个。")}
       stepper
-      primaryLabel="继续"
+      primaryLabel={t("继续")}
       onPrimary={() => navigate("/setup/mode")}
       primaryDisabled={!state.selectedAgentIds.length || state.statusState === "loading"}
-      footerNote={state.selectedAgentIds.length ? `已选择 ${state.selectedAgentIds.length} 个 Agent` : "至少选择一个 Agent"}
+      footerNote={state.selectedAgentIds.length ? t("已选择 {count} 个 Agent", { count: state.selectedAgentIds.length }) : t("至少选择一个 Agent")}
       bodyClassName="agent-selection-body"
     >
-      {state.statusState === "loading" ? <div className="loading-block"><span className="spinner" />正在检测本机环境</div> : null}
+      {state.statusState === "loading" ? <div className="loading-block"><span className="spinner" />{t("正在检测本机环境")}</div> : null}
       {state.statusError ? <div className="notice notice-error">{state.statusError}</div> : null}
       {state.status ? (
         <>
           <section className="content-section">
             <div className="section-heading">
               <div>
-                <h2>常用 Agent</h2>
-                <p>可一键配置的使用锁定版本完成初始化，仅引导的只显示官方步骤。</p>
+                <h2>{t("常用 Agent")}</h2>
+                <p>{t("可一键配置的使用锁定版本完成初始化，仅引导的只显示官方步骤。")}</p>
               </div>
               <PackageCheck size={19} aria-hidden="true" />
             </div>
@@ -61,16 +64,16 @@ export function AgentSelectionPage() {
           <section className={`disclosure-section${showMore ? " is-open" : ""}`}>
             <button type="button" className="disclosure-trigger" onClick={() => setShowMore((value) => !value)} aria-expanded={showMore}>
               <ChevronDown size={18} />
-              更多 Agent（{secondary.length}）
-              <span>网关、平台账号与 IDE 扩展</span>
+              {t("更多 Agent（{count}）", { count: secondary.length })}
+              <span>{t("网关、平台账号与 IDE 扩展")}</span>
             </button>
             {showMore ? <div className="additional-agent-groups">{renderRows(secondary)}</div> : null}
           </section>
 
           <label className="toggle-row">
             <span>
-              <strong>安装缺失的 Agent</strong>
-              <small>仅调用 lock manifest 中允许的官方 npm 或 pip 包。</small>
+              <strong>{t("安装缺失的 Agent")}</strong>
+              <small>{t("仅调用 lock manifest 中允许的官方 npm 或 uv 包。")}</small>
             </span>
             <input
               type="checkbox"
@@ -79,6 +82,20 @@ export function AgentSelectionPage() {
               onChange={(event) => dispatch({ type: "SET_INSTALL_MISSING", value: event.target.checked })}
             />
           </label>
+
+          {/* Installing a selected Agent needs its package manager. Offering the
+              runtime here, before the wizard collects a key and a model, keeps the
+              activation run from failing on a prerequisite the user cannot fix
+              from the last step. */}
+          {state.installMissingAgents ? (
+            <RuntimePrompt
+              runtimes={state.status.runtimes ?? []}
+              missingRuntime={state.status.capabilities.missingRuntime ?? {}}
+              selectedAgentIds={state.selectedAgentIds}
+              agents={state.status.agents}
+              onInstalled={refreshStatus}
+            />
+          ) : null}
         </>
       ) : null}
     </PageScaffold>
diff --git a/frontend/src/pages/ConfigModePage.tsx b/frontend/src/pages/ConfigModePage.tsx
index d3e750ee..1a7d42cc 100644
--- a/frontend/src/pages/ConfigModePage.tsx
+++ b/frontend/src/pages/ConfigModePage.tsx
@@ -3,41 +3,43 @@ import { useNavigate } from "react-router-dom";
 
 import { ChoiceRow } from "../components/ChoiceRow";
 import { PageScaffold } from "../components/PageScaffold";
+import { useI18n } from "../i18n";
 import { useWizard } from "../state/WizardContext";
 
 export function ConfigModePage() {
   const navigate = useNavigate();
+  const { t } = useI18n();
   const { state, dispatch } = useWizard();
   return (
     <PageScaffold
-      title="配置方式"
-      description="选择由 OneAgent 初始化模型服务，或保留已有官方账号与本机配置。"
+      title={t("配置方式")}
+      description={t("选择由 OneAgent 初始化模型服务，或保留已有官方账号与本机配置。")}
       stepper
       onBack={() => navigate("/setup/agents")}
-      primaryLabel="继续"
+      primaryLabel={t("继续")}
       onPrimary={() => navigate(state.configMode === "existing-account" ? "/setup/review" : "/setup/provider")}
       primaryDisabled={!state.configMode}
-      footerNote={state.configMode === "existing-account" ? "Provider 与模型步骤将标记为已跳过" : undefined}
+      footerNote={state.configMode === "existing-account" ? t("Provider 与模型步骤将标记为已跳过") : undefined}
     >
       <div className="choice-list">
         <ChoiceRow
           selected={state.configMode === "provider"}
-          title="配置模型服务"
-          description="选择 PPIO、Novita 或自定义 OpenAI-compatible 服务。"
-          detail="OneAgent 将测试连接、发现模型并写入本机配置。"
+          title={t("配置模型服务")}
+          description={t("选择 PPIO、Novita 或自定义 OpenAI-compatible 服务。")}
+          detail={t("OneAgent 将测试连接、发现模型并写入本机配置。")}
           icon={KeyRound}
           onSelect={() => dispatch({ type: "SET_CONFIG_MODE", value: "provider" })}
         />
         <ChoiceRow
           selected={state.configMode === "existing-account"}
-          title="使用已有账号或配置"
-          description="只检测或安装 Agent，不写入第三方模型服务配置。"
-          detail="适合已登录官方账号，或已经维护本机配置的用户。"
+          title={t("使用已有账号或配置")}
+          description={t("只检测或安装 Agent，不写入第三方模型服务配置。")}
+          detail={t("适合已登录官方账号，或已经维护本机配置的用户。")}
           icon={UserCheck}
           onSelect={() => dispatch({ type: "SET_CONFIG_MODE", value: "existing-account" })}
         />
       </div>
-      <div className="notice notice-info">跳过配置不会删除或覆盖现有 Agent 设置。</div>
+      <div className="notice notice-info">{t("跳过配置不会删除或覆盖现有 Agent 设置。")}</div>
     </PageScaffold>
   );
 }
diff --git a/frontend/src/pages/EnvironmentOverviewPage.test.tsx b/frontend/src/pages/EnvironmentOverviewPage.test.tsx
new file mode 100644
index 00000000..ed37f9f4
--- /dev/null
+++ b/frontend/src/pages/EnvironmentOverviewPage.test.tsx
@@ -0,0 +1,70 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import type { StatusResponse } from "../types/api";
+import { EnvironmentOverviewPage } from "./EnvironmentOverviewPage";
+
+vi.mock("../state/WizardContext", () => ({
+  useWizard: () => ({ state: mockState, refreshStatus: vi.fn() }),
+}));
+
+let mockState: { status: StatusResponse | null; statusState: string; statusError: string };
+
+function status(): StatusResponse {
+  const agent = (installed: boolean, profileId: string | null) => ({
+    installed,
+    configured: installed,
+    guideOnly: false,
+    config: "/config",
+    version: installed ? "1.0.0" : null,
+    lockedVersion: "1.0.0",
+    canInstall: true,
+    provider: installed ? "ppio" : null,
+    profileId,
+    model: installed ? "model-a" : null,
+    baseUrl: installed ? "https://api.ppio.com/openai" : null,
+    updatedAt: null,
+    detected: null,
+  });
+  return {
+    apiVersion: 1,
+    platform: { os: "macos", arch: "arm64", shell: "zsh" },
+    runtimes: [],
+    capabilities: { canInstall: {}, missingRuntime: {}, supportedAgentIds: [] },
+    agents: { codex: agent(true, "team"), opencode: agent(false, null) },
+    catalog: [
+      { id: "opencode", name: "OpenCode", group: "auto", configMode: "auto", guideOnly: false, lockedVersion: "1.0.0", protocol: "openai", platforms: ["macos"], platformNote: "", rank: 4 },
+      { id: "codex", name: "Codex", group: "auto", configMode: "auto", guideOnly: false, lockedVersion: "1.0.0", protocol: "responses", platforms: ["macos"], platformNote: "", rank: 1 },
+    ],
+    groups: [],
+    providers: { ppio: { name: "PPIO", home: "https://ppio.com/", base_url: "https://api.ppio.com/openai" } },
+    mirrors: [],
+    paths: {},
+    backups: {},
+    profiles: [{ id: "team", label: "团队默认", provider: "ppio", baseUrl: null, model: "model-a", agentIds: ["codex"], activatedAt: null, hasKey: true }],
+    activeProfile: "team",
+    environment: null,
+    environmentError: null,
+  };
+}
+
+describe("EnvironmentOverviewPage", () => {
+  it("shows only installed Agents with their Provider and Profile", () => {
+    mockState = { status: status(), statusState: "success", statusError: "" };
+    render(<EnvironmentOverviewPage />);
+    expect(screen.getByText("Codex")).toBeTruthy();
+    expect(screen.queryByText("OpenCode")).toBeNull();
+    expect(screen.getByText("PPIO")).toBeTruthy();
+    expect(screen.getByText("团队默认")).toBeTruthy();
+    expect(screen.queryByRole("button", { name: /配置|安装/ })).toBeNull();
+  });
+
+  it("keeps an empty environment informational", () => {
+    const empty = status();
+    empty.agents.codex.installed = false;
+    mockState = { status: empty, statusState: "success", statusError: "" };
+    render(<EnvironmentOverviewPage />);
+    expect(screen.getByText("尚未安装任何 Agent")).toBeTruthy();
+    expect(screen.queryByRole("button", { name: /开始|新建/ })).toBeNull();
+  });
+});
diff --git a/frontend/src/pages/EnvironmentOverviewPage.tsx b/frontend/src/pages/EnvironmentOverviewPage.tsx
index 54035ba0..f0a8c0dc 100644
--- a/frontend/src/pages/EnvironmentOverviewPage.tsx
+++ b/frontend/src/pages/EnvironmentOverviewPage.tsx
@@ -1,76 +1,45 @@
-import { RefreshCw, RotateCcw } from "lucide-react";
-import { useState } from "react";
-import { useNavigate } from "react-router-dom";
+import { PackageOpen, RefreshCw } from "lucide-react";
 
-import { AgentManageRow, isBehind } from "../components/AgentManageRow";
-import { GuideOnlyRow } from "../components/GuideOnlyRow";
+import { AgentManageRow } from "../components/AgentManageRow";
 import { PageScaffold } from "../components/PageScaffold";
-import { splitByRank } from "../state/ranking";
+import { RuntimeSection } from "../components/RuntimeSection";
+import { useI18n } from "../i18n";
 import { useWizard } from "../state/WizardContext";
 
 export function EnvironmentOverviewPage() {
-  const navigate = useNavigate();
-  const { state, dispatch, refreshStatus } = useWizard();
-  const [showGuideOnly, setShowGuideOnly] = useState(false);
+  const { t } = useI18n();
+  const { state, refreshStatus } = useWizard();
   const status = state.status;
 
   if (state.statusState === "loading" && !status) {
     return (
-      <PageScaffold title="环境总览">
-        <div className="loading-block"><span className="spinner" />正在读取环境状态</div>
+      <PageScaffold title={t("环境总览")}>
+        <div className="loading-block"><span className="spinner" />{t("正在读取环境状态")}</div>
       </PageScaffold>
     );
   }
 
-  const catalogById = new Map(status?.catalog.map((item) => [item.id, item]) ?? []);
-  const managed = (status?.catalog ?? []).filter((item) => item.configMode === "auto");
-  const { primary, secondary } = splitByRank(status?.catalog);
-
-  // Either kind of evidence counts as "configured". A per-Agent binding covers
-  // an Agent set up through "oneagent agent set", which has no environment
-  // profile; the profile covers a wizard run whose bindings have not been
-  // re-read yet. Requiring only bindings would report a freshly finished wizard
-  // as "nothing configured".
-  const configuredCount = managed.filter((item) => status?.agents[item.id]?.provider).length;
-  const hasAnyConfiguration = Boolean(status?.environment) || configuredCount > 0;
-
-  if (!status || !hasAnyConfiguration) {
+  if (!status) {
     return (
-      <PageScaffold
-        title="环境总览"
-        description="还没有 Agent 指向任何模型服务。"
-        primaryLabel="开始配置"
-        onPrimary={() => navigate("/setup/agents")}
-      >
+      <PageScaffold title={t("环境总览")} description={t("本机已安装 Agent 及其当前配置。")}>
         <div className="empty-overview">
-          <RotateCcw size={28} />
-          <strong>尚未配置任何 Agent</strong>
-          <span>{status?.environmentError || "完成一次配置后，这里会列出每个 Agent 指向的 Provider 与模型，并可随时单独调整。"}</span>
+          <PackageOpen size={28} />
+          <strong>{t("无法读取环境状态")}</strong>
+          <span>{state.statusError || t("请刷新后重试。")}</span>
         </div>
       </PageScaffold>
     );
   }
 
-  // Behind means older than the locked version, not merely different: a user
-  // who upgraded an Agent themselves is ahead, and counting that as an update
-  // would nag them to downgrade.
-  const behind = managed.filter((item) => {
-    const agent = status.agents[item.id];
-    return Boolean(
-      agent?.installed && agent.version && agent.lockedVersion && isBehind(agent.version, agent.lockedVersion),
-    );
-  });
-  const unconfigured = managed.filter((item) => status.agents[item.id]?.installed && !status.agents[item.id]?.provider);
+  const installed = [...status.catalog]
+    .sort((first, second) => first.rank - second.rank)
+    .filter((item) => status.agents[item.id]?.installed);
+  const profiles = new Map(status.profiles.map((profile) => [profile.id, profile.label]));
 
   return (
     <PageScaffold
-      title="环境总览"
-      titleBadge={behind.length ? `${behind.length} 项可更新` : ""}
-      primaryLabel="新建配置"
-      onPrimary={() => {
-        dispatch({ type: "RESET_SETUP" });
-        navigate("/setup/agents");
-      }}
+      title={t("环境总览")}
+      description={t("本机已安装 Agent 及其当前 Provider、Profile 与模型。")}
       secondaryAction={
         <button
           className="button button-secondary"
@@ -79,64 +48,39 @@ export function EnvironmentOverviewPage() {
           disabled={state.statusState === "loading"}
         >
           <RefreshCw size={15} className={state.statusState === "loading" ? "spin" : ""} />
-          刷新状态
+          {t("刷新状态")}
         </button>
       }
     >
-      <section className="overview-section">
-        <div className="agent-manage-list">
-          {primary.map((item) => {
-            const agent = status.agents[item.id];
-            if (item.configMode !== "auto") {
-              return <GuideOnlyRow key={item.id} agentId={item.id} catalog={item} status={agent} />;
-            }
-            if (!agent) return null;
-            return (
-              <AgentManageRow
+      <RuntimeSection runtimes={status.runtimes ?? []} onInstalled={refreshStatus} />
+
+      {installed.length ? (
+        <section className="overview-section">
+          <div className="section-heading">
+            <div><h2>{t("已安装 Agent")}</h2><p>{t("共 {count} 个", { count: installed.length })}</p></div>
+          </div>
+          <div className="agent-manage-list">
+            {installed.map((item) => {
+              const agent = status.agents[item.id];
+              if (!agent) return null;
+              return <AgentManageRow
                 key={item.id}
                 agentId={item.id}
-                catalog={catalogById.get(item.id)}
+                catalog={item}
                 status={agent}
                 providers={status.providers}
-                onOpen={() => navigate(`/agents/${item.id}`)}
-              />
-            );
-          })}
-        </div>
-      </section>
-
-      <section className="overview-section">
-        <button
-          className="disclosure-trigger"
-          type="button"
-          aria-expanded={showGuideOnly}
-          onClick={() => setShowGuideOnly((value) => !value)}
-        >
-          其他 Agent（{secondary.length}）
-        </button>
-        {showGuideOnly ? (
-          <div className="overview-agent-list">
-            {secondary.map((item) => {
-              const agent = status.agents[item.id];
-              if (item.configMode !== "auto") {
-                return <GuideOnlyRow key={item.id} agentId={item.id} catalog={item} status={agent} />;
-              }
-              if (!agent) return null;
-              return (
-                <AgentManageRow
-                  key={item.id}
-                  agentId={item.id}
-                  catalog={item}
-                  status={agent}
-                  providers={status.providers}
-                  onOpen={() => navigate(`/agents/${item.id}`)}
-                />
-              );
+                profileName={agent.profileId ? profiles.get(agent.profileId) || agent.profileId : ""}
+              />;
             })}
           </div>
-        ) : null}
-      </section>
-
+        </section>
+      ) : (
+        <div className="empty-overview">
+          <PackageOpen size={28} />
+          <strong>{t("尚未安装任何 Agent")}</strong>
+          <span>{t("在配置模板中创建 Profile 并应用后，已安装的 Agent 会显示在这里。")}</span>
+        </div>
+      )}
     </PageScaffold>
   );
 }
diff --git a/frontend/src/pages/LandingPage.tsx b/frontend/src/pages/LandingPage.tsx
deleted file mode 100644
index de1da036..00000000
--- a/frontend/src/pages/LandingPage.tsx
+++ /dev/null
@@ -1,480 +0,0 @@
-import { useState } from "react";
-import {
-  ArrowRight,
-  ArrowUpRight,
-  Bot,
-  Check,
-  ChevronDown,
-  Command,
-  GitBranch,
-  Layers3,
-  Menu,
-  Network,
-  ShieldCheck,
-  Sparkles,
-  TerminalSquare,
-  X,
-  Zap,
-} from "lucide-react";
-import { Link } from "react-router-dom";
-
-type DemoTab = "overview" | "routing" | "profiles";
-
-const demoTabs: Array<{ id: DemoTab; label: string }> = [
-  { id: "overview", label: "Overview" },
-  { id: "routing", label: "Routing" },
-  { id: "profiles", label: "Profiles" },
-];
-
-const agents = [
-  { name: "Codex", detail: "Responses API", tone: "coral" },
-  { name: "Claude Code", detail: "Anthropic", tone: "mint" },
-  { name: "OpenCode", detail: "OpenAI compatible", tone: "blue" },
-  { name: "Aider", detail: "Terminal workflow", tone: "gold" },
-];
-
-const faqs = [
-  {
-    question: "Does OneAgent replace my coding agents?",
-    answer:
-      "No. OneAgent sits beside them as a small control plane. You keep the tools you already like and use OneAgent to manage the provider, model, and profile each one should use.",
-  },
-  {
-    question: "Where does my configuration live?",
-    answer:
-      "Locally by default. OneAgent keeps the working configuration on your machine and gives you an explicit view of what each agent is connected to before you apply a change.",
-  },
-  {
-    question: "Can different agents use different models?",
-    answer:
-      "Yes. Each agent gets its own lane, so a terminal agent can use one provider while an IDE extension or review agent uses another. Switch the binding without editing scattered dotfiles.",
-  },
-];
-
-function scrollToSection(id: string) {
-  document.getElementById(id)?.scrollIntoView({ behavior: "smooth", block: "start" });
-}
-
-function BrandMark() {
-  return (
-    <span className="landing-brand-mark" aria-hidden="true">
-      <span className="landing-brand-node landing-brand-node-left" />
-      <span className="landing-brand-node landing-brand-node-right" />
-      <span className="landing-brand-node landing-brand-node-bottom" />
-      <span className="landing-brand-link landing-brand-link-one" />
-      <span className="landing-brand-link landing-brand-link-two" />
-    </span>
-  );
-}
-
-function NetworkMap() {
-  return (
-    <div className="network-map" aria-label="OneAgent routing map preview" role="img">
-      <div className="network-map-grid" />
-      <svg className="network-map-lines" viewBox="0 0 640 430" aria-hidden="true">
-        <path d="M320 212 C256 184 182 144 98 93" />
-        <path d="M320 212 C386 182 464 145 548 94" />
-        <path d="M320 212 C248 258 178 294 102 344" />
-        <path d="M320 212 C393 256 465 298 548 344" />
-        <circle cx="98" cy="93" r="4" />
-        <circle cx="548" cy="94" r="4" />
-        <circle cx="102" cy="344" r="4" />
-        <circle cx="548" cy="344" r="4" />
-      </svg>
-
-      <div className="network-map-radar network-map-radar-one" />
-      <div className="network-map-radar network-map-radar-two" />
-
-      <div className="network-core">
-        <div className="network-core-orbit" />
-        <div className="network-core-icon"><Network size={22} strokeWidth={1.8} /></div>
-        <strong>OneAgent</strong>
-        <span>control plane</span>
-      </div>
-
-      {agents.map((agent, index) => (
-        <div className={`network-agent network-agent-${index + 1}`} key={agent.name}>
-          <span className={`network-agent-dot network-agent-dot-${agent.tone}`} />
-          <span>
-            <strong>{agent.name}</strong>
-            <small>{agent.detail}</small>
-          </span>
-          <span className="network-agent-state">ready</span>
-        </div>
-      ))}
-
-      <div className="network-map-caption">
-        <span><span className="network-live-dot" /> local workspace</span>
-        <span>profile / default</span>
-      </div>
-    </div>
-  );
-}
-
-function DemoOverview() {
-  return (
-    <div className="demo-panel-content demo-overview">
-      <div className="demo-status-row">
-        <div>
-          <span className="demo-overline">WORKSPACE</span>
-          <strong>Personal · default</strong>
-        </div>
-        <span className="demo-ready"><span /> All systems ready</span>
-      </div>
-      <div className="demo-agent-list">
-        {agents.slice(0, 3).map((agent, index) => (
-          <div className="demo-agent-row" key={agent.name}>
-            <span className={`demo-agent-avatar demo-agent-avatar-${agent.tone}`}>
-              {index === 0 ? <TerminalSquare size={14} /> : index === 1 ? <Bot size={14} /> : <Command size={14} />}
-            </span>
-            <span className="demo-agent-name"><strong>{agent.name}</strong><small>{agent.detail}</small></span>
-            <span className="demo-agent-model">{index === 0 ? "gpt-5-codex" : index === 1 ? "claude-sonnet" : "deepseek-v3"}</span>
-            <Check size={15} className="demo-check" />
-          </div>
-        ))}
-      </div>
-      <div className="demo-footer-row">
-        <span><span className="demo-mini-dot" /> Changes are local</span>
-        <span>Updated just now</span>
-      </div>
-    </div>
-  );
-}
-
-function DemoRouting() {
-  return (
-    <div className="demo-panel-content demo-routing">
-      <div className="demo-routing-header">
-        <div>
-          <span className="demo-overline">REQUEST PATH</span>
-          <strong>agent → profile → provider</strong>
-        </div>
-        <span className="demo-route-badge">3 hops</span>
-      </div>
-      <div className="route-track">
-        <div className="route-node route-node-coral"><TerminalSquare size={16} /><span>Codex</span><small>agent</small></div>
-        <span className="route-line"><i /></span>
-        <div className="route-node route-node-mint"><Layers3 size={16} /><span>default</span><small>profile</small></div>
-        <span className="route-line"><i /></span>
-        <div className="route-node route-node-blue"><Zap size={16} /><span>PPIO</span><small>provider</small></div>
-      </div>
-      <div className="route-code">
-        <span className="code-muted">$</span> oneagent agent set codex
-        <br />
-        <span className="code-muted">→</span> profile <b>default</b> · model <b>gpt-5-codex</b>
-      </div>
-      <div className="demo-footer-row"><span><span className="demo-mini-dot demo-mini-dot-coral" /> Applied without touching your prompt</span></div>
-    </div>
-  );
-}
-
-function DemoProfiles() {
-  return (
-    <div className="demo-panel-content demo-profiles">
-      <div className="demo-status-row">
-        <div>
-          <span className="demo-overline">SAVED PROFILES</span>
-          <strong>Switch context, not config files</strong>
-        </div>
-        <span className="demo-add-profile">＋ New profile</span>
-      </div>
-      <div className="profile-preview-list">
-        <div className="profile-preview profile-preview-active">
-          <div className="profile-preview-top"><span className="profile-symbol profile-symbol-coral">⌁</span><strong>default</strong><span className="profile-current">current</span></div>
-          <p>Balanced for everyday building and review.</p>
-          <div className="profile-preview-meta"><span>3 agents</span><span>2 providers</span></div>
-        </div>
-        <div className="profile-preview">
-          <div className="profile-preview-top"><span className="profile-symbol profile-symbol-mint">✦</span><strong>deep-work</strong></div>
-          <p>Higher reasoning budget for long-running tasks.</p>
-          <div className="profile-preview-meta"><span>1 agent</span><span>1 provider</span></div>
-        </div>
-      </div>
-    </div>
-  );
-}
-
-function DemoPanel({ activeTab }: { activeTab: DemoTab }) {
-  if (activeTab === "routing") return <DemoRouting />;
-  if (activeTab === "profiles") return <DemoProfiles />;
-  return <DemoOverview />;
-}
-
-function AppWordmark() {
-  return (
-    <Link className="landing-wordmark" to="/" aria-label="OneAgent home">
-      <BrandMark />
-      <span>OneAgent</span>
-    </Link>
-  );
-}
-
-export function LandingPage() {
-  const [activeDemo, setActiveDemo] = useState<DemoTab>("overview");
-  const [mobileOpen, setMobileOpen] = useState(false);
-  const [openFaq, setOpenFaq] = useState<number | null>(0);
-
-  const goTo = (id: string) => {
-    setMobileOpen(false);
-    scrollToSection(id);
-  };
-
-  return (
-    <div className="landing-shell">
-      <div className="landing-background-grid" aria-hidden="true" />
-      <header className="landing-header">
-        <nav className="landing-nav" aria-label="Primary navigation">
-          <AppWordmark />
-          <div className={`landing-nav-links${mobileOpen ? " is-open" : ""}`}>
-            <button type="button" onClick={() => goTo("product")}>Product</button>
-            <button type="button" onClick={() => goTo("workflow")}>Workflow</button>
-            <button type="button" onClick={() => goTo("teams")}>For teams</button>
-            <button type="button" onClick={() => goTo("faq")}>FAQ</button>
-            <Link className="landing-nav-cta landing-nav-cta-mobile" to="/setup/agents">Open workspace <ArrowUpRight size={15} /></Link>
-          </div>
-          <div className="landing-nav-actions">
-            <Link className="landing-nav-login" to="/setup/agents">Sign in</Link>
-            <Link className="landing-nav-cta" to="/setup/agents">Open workspace <ArrowUpRight size={15} /></Link>
-            <button
-              className="landing-mobile-toggle"
-              type="button"
-              aria-label={mobileOpen ? "Close menu" : "Open menu"}
-              aria-expanded={mobileOpen}
-              onClick={() => setMobileOpen((value) => !value)}
-            >
-              {mobileOpen ? <X size={21} /> : <Menu size={21} />}
-            </button>
-          </div>
-        </nav>
-      </header>
-
-      <main>
-        <section className="landing-hero" aria-labelledby="hero-heading">
-          <div className="hero-copy">
-            <h1 id="hero-heading">All your agents.<br /><span>One clear lane.</span></h1>
-            <p className="hero-lede">
-              OneAgent is the calm control plane for coding agents. Keep providers, models, and profiles in one place — then get back to the work that made you open the terminal.
-            </p>
-            <div className="hero-actions">
-              <Link className="landing-button landing-button-primary" to="/setup/agents">
-                Start with OneAgent <ArrowRight size={17} />
-              </Link>
-              <button className="landing-button landing-button-quiet" type="button" onClick={() => goTo("workflow")}>
-                See the workflow <span className="button-arrow">↘</span>
-              </button>
-            </div>
-            <div className="hero-note"><span className="hero-note-dot" /> Local-first by default <span className="hero-note-divider" /> No scattered dotfiles</div>
-          </div>
-          <div className="hero-visual-wrap">
-            <div className="hero-visual-label"><span>LIVE ROUTING MAP</span><span><span className="hero-live-dot" /> synced</span></div>
-            <NetworkMap />
-            <div className="hero-visual-footnote"><span>OneAgent workspace</span><span>macOS · local</span></div>
-          </div>
-        </section>
-
-        <section className="tool-strip" aria-label="Supported agent tools">
-          <span className="tool-strip-label">Works with the tools already in your terminal</span>
-          <div className="tool-strip-list">
-            <span className="tool-name"><TerminalSquare size={16} /> Codex</span>
-            <span className="tool-name"><Bot size={16} /> Claude Code</span>
-            <span className="tool-name"><Command size={16} /> OpenCode</span>
-            <span className="tool-name"><GitBranch size={16} /> Aider</span>
-            <span className="tool-name"><Sparkles size={16} /> Kilo CLI</span>
-          </div>
-        </section>
-
-        <section className="landing-section landing-section-paper" id="product" aria-labelledby="product-heading">
-          <div className="landing-section-inner">
-            <div className="section-heading-row">
-              <span className="section-index">01</span>
-              <div className="section-heading-copy">
-                <h2 id="product-heading">The messy part is the handoff.</h2>
-                <p>Provider changes should not mean hunting through five config files, remembering which agent uses which model, and hoping the next restart picked it up.</p>
-              </div>
-            </div>
-            <div className="friction-layout">
-              <div className="friction-statement">
-                <span className="friction-quote-mark">“</span>
-                <p>Move from <em>where is this configured?</em> to <strong>ship the change</strong>.</p>
-                <span className="friction-rule" />
-                <span className="friction-caption">One place to see the decision. One action to apply it.</span>
-              </div>
-              <div className="friction-list">
-                <div className="friction-item">
-                  <span className="friction-icon friction-icon-coral"><Command size={18} /></span>
-                  <div><strong>Choose once</strong><span>Bind each agent to the provider and model that fit its job.</span></div>
-                  <span className="friction-number">01</span>
-                </div>
-                <div className="friction-item">
-                  <span className="friction-icon friction-icon-mint"><Layers3 size={18} /></span>
-                  <div><strong>Save the shape</strong><span>Keep a named profile for a project, a client, or a different mode of thinking.</span></div>
-                  <span className="friction-number">02</span>
-                </div>
-                <div className="friction-item">
-                  <span className="friction-icon friction-icon-blue"><Zap size={18} /></span>
-                  <div><strong>Apply with confidence</strong><span>See the resulting route before you restart anything.</span></div>
-                  <span className="friction-number">03</span>
-                </div>
-              </div>
-            </div>
-          </div>
-        </section>
-
-        <section className="landing-section landing-section-ink" id="workflow" aria-labelledby="workflow-heading">
-          <div className="landing-section-inner workflow-section-inner">
-            <div className="section-heading-row section-heading-row-dark">
-              <span className="section-index">02</span>
-              <div className="section-heading-copy">
-                <h2 id="workflow-heading">From provider swap to done in three moves.</h2>
-                <p>OneAgent keeps the mental model small: select the lane, preview the route, apply the change.</p>
-              </div>
-            </div>
-
-            <div className="workflow-layout">
-              <div className="workflow-steps">
-                <div className="workflow-step workflow-step-active">
-                  <span className="workflow-step-number">01</span>
-                  <div><strong>Pick the agents</strong><p>Start with the tools you actually use. Nothing else gets touched.</p></div>
-                  <Check size={18} />
-                </div>
-                <div className="workflow-step">
-                  <span className="workflow-step-number">02</span>
-                  <div><strong>Choose the route</strong><p>Pair a profile with a provider and model — per agent, not per machine.</p></div>
-                  <ArrowRight size={18} />
-                </div>
-                <div className="workflow-step">
-                  <span className="workflow-step-number">03</span>
-                  <div><strong>Keep moving</strong><p>Apply once, restart when you are ready, and return to a legible workspace.</p></div>
-                  <ArrowRight size={18} />
-                </div>
-                <Link className="workflow-link" to="/setup/agents">Open the real setup flow <ArrowUpRight size={16} /></Link>
-              </div>
-
-              <div className="demo-window" id="demo-preview">
-                <div className="demo-window-bar">
-                  <div className="demo-window-lights"><span /><span /><span /></div>
-                  <span>oneagent / workspace</span>
-                  <span className="demo-window-privacy"><ShieldCheck size={13} /> local</span>
-                </div>
-                <div className="demo-tabs" role="tablist" aria-label="OneAgent preview">
-                  {demoTabs.map((tab) => (
-                    <button
-                      key={tab.id}
-                      className={`demo-tab${activeDemo === tab.id ? " is-active" : ""}`}
-                      type="button"
-                      role="tab"
-                      aria-selected={activeDemo === tab.id}
-                      onClick={() => setActiveDemo(tab.id)}
-                    >
-                      {tab.label}
-                    </button>
-                  ))}
-                </div>
-                <DemoPanel activeTab={activeDemo} />
-              </div>
-            </div>
-          </div>
-        </section>
-
-        <section className="landing-section landing-section-paper landing-section-lanes" id="teams" aria-labelledby="teams-heading">
-          <div className="landing-section-inner">
-            <div className="section-heading-row">
-              <span className="section-index">03</span>
-              <div className="section-heading-copy">
-                <h2 id="teams-heading">Every agent gets its own lane.</h2>
-                <p>Keep the team’s tooling flexible without turning the workspace into a shared mystery.</p>
-              </div>
-            </div>
-            <div className="lanes-layout">
-              <div className="lanes-copy">
-                <div className="lanes-copy-head"><span className="lanes-kicker">A SMALLER SURFACE AREA</span><Network size={22} /></div>
-                <p>OneAgent makes the invisible parts of an AI development stack inspectable: who is connected, where requests go, and which profile is active.</p>
-                <ul className="check-list">
-                  <li><Check size={16} /> Per-agent provider bindings</li>
-                  <li><Check size={16} /> Named profiles for repeatable context</li>
-                  <li><Check size={16} /> A readable preview before activation</li>
-                </ul>
-                <Link className="text-link" to="/setup/agents">Explore the workspace <ArrowUpRight size={16} /></Link>
-              </div>
-              <div className="lane-stack" aria-label="Agent lanes preview">
-                {agents.map((agent, index) => (
-                  <div className={`lane-row lane-row-${agent.tone}`} key={agent.name}>
-                    <span className="lane-order">0{index + 1}</span>
-                    <span className="lane-color-bar" />
-                    <span className="lane-agent"><strong>{agent.name}</strong><small>{agent.detail}</small></span>
-                    <span className="lane-route"><span>profile / {index === 1 ? "deep-work" : "default"}</span><ArrowRight size={14} /><span>{index === 2 ? "Novita" : "PPIO"}</span></span>
-                    <span className="lane-state"><span /> ready</span>
-                  </div>
-                ))}
-                <div className="lane-stack-foot"><span>4 lanes</span><span>1 workspace</span><span>0 guesswork</span></div>
-              </div>
-            </div>
-          </div>
-        </section>
-
-        <section className="principles-section" aria-labelledby="principles-heading">
-          <div className="principles-inner">
-            <div className="principles-orbit" aria-hidden="true">
-              <span className="principles-orbit-ring principles-orbit-ring-one" />
-              <span className="principles-orbit-ring principles-orbit-ring-two" />
-              <span className="principles-orbit-core"><ShieldCheck size={26} /></span>
-            </div>
-            <div className="principles-copy">
-              <span className="section-index section-index-accent">04</span>
-              <h2 id="principles-heading">The best infrastructure disappears into clarity.</h2>
-              <p>OneAgent is intentionally small, local, and explicit. It gives your team a shared vocabulary for model routing without asking your workflow to become a new platform.</p>
-              <div className="principles-notes">
-                <span><span className="principle-dot principle-dot-mint" /> Local by default</span>
-                <span><span className="principle-dot principle-dot-coral" /> Explicit before apply</span>
-                <span><span className="principle-dot principle-dot-gold" /> Easy to return to</span>
-              </div>
-            </div>
-          </div>
-        </section>
-
-        <section className="faq-section" id="faq" aria-labelledby="faq-heading">
-          <div className="landing-section-inner faq-inner">
-            <div className="faq-intro">
-              <span className="section-index">05</span>
-              <h2 id="faq-heading">A few good questions.</h2>
-              <p>Short answers for the moment before you open the workspace.</p>
-            </div>
-            <div className="faq-list">
-              {faqs.map((faq, index) => {
-                const isOpen = openFaq === index;
-                return (
-                  <div className={`faq-item${isOpen ? " is-open" : ""}`} key={faq.question}>
-                    <button type="button" aria-expanded={isOpen} onClick={() => setOpenFaq(isOpen ? null : index)}>
-                      <span>{faq.question}</span>
-                      <ChevronDown size={18} />
-                    </button>
-                    <div className="faq-answer" hidden={!isOpen}><p>{faq.answer}</p></div>
-                  </div>
-                );
-              })}
-            </div>
-          </div>
-        </section>
-
-        <section className="final-cta" aria-labelledby="final-cta-heading">
-          <div className="final-cta-grid" aria-hidden="true" />
-          <div className="final-cta-inner">
-            <div className="final-cta-mark"><BrandMark /></div>
-            <h2 id="final-cta-heading">Make the next model swap boring.</h2>
-            <p>Set up your agents once. Keep the useful part of your attention for the work itself.</p>
-            <Link className="landing-button landing-button-primary landing-button-final" to="/setup/agents">Open OneAgent <ArrowRight size={17} /></Link>
-            <span className="final-cta-note">No account wall. No new editor. Just a clearer route.</span>
-          </div>
-        </section>
-      </main>
-
-      <footer className="landing-footer">
-        <div className="landing-footer-inner">
-          <AppWordmark />
-          <span className="landing-footer-copy">One control plane for the tools that build with you.</span>
-          <div className="landing-footer-links"><Link to="/setup/agents">Workspace</Link><button type="button" onClick={() => scrollToSection("faq")}>FAQ</button><span>© 2026 OneAgent</span></div>
-        </div>
-      </footer>
-    </div>
-  );
-}
diff --git a/frontend/src/pages/ModelSelectionPage.tsx b/frontend/src/pages/ModelSelectionPage.tsx
index bdcfd157..8495a024 100644
--- a/frontend/src/pages/ModelSelectionPage.tsx
+++ b/frontend/src/pages/ModelSelectionPage.tsx
@@ -2,55 +2,57 @@ import { RefreshCw } from "lucide-react";
 import { useCallback, useEffect, useRef } from "react";
 import { useNavigate } from "react-router-dom";
 
-import { api, describeError } from "../api/client";
+import { api, describeError } from "../backend/api";
 import { ModelPicker } from "../components/ModelPicker";
 import { PageScaffold } from "../components/PageScaffold";
+import { useI18n } from "../i18n";
 import { useWizard } from "../state/WizardContext";
 
 export function ModelSelectionPage() {
   const navigate = useNavigate();
+  const { t } = useI18n();
   const { state, dispatch, secret } = useWizard();
   const requested = useRef(false);
 
-  const fetchModels = useCallback(async () => {
+  const loadModels = useCallback(async () => {
     dispatch({ type: "MODELS_LOADING" });
     try {
       const result = await api.models({
         provider: state.provider,
-        apiBaseUrl: state.provider === "custom" ? state.customBaseUrl : "",
+        apiBaseUrl: "",
         apiKey: secret.keyRef.current,
       });
       dispatch({ type: "MODELS_RESULT", result });
     } catch (error) {
-      dispatch({ type: "MODELS_FAILED", message: describeError(error, "无法获取模型列表").message });
+      dispatch({ type: "MODELS_FAILED", message: describeError(error, t("无法获取模型列表")).message });
     }
-  }, [dispatch, secret.keyRef, state.customBaseUrl, state.provider]);
+  }, [dispatch, secret.keyRef, state.provider, t]);
 
   useEffect(() => {
-    // SetupGuard has already verified the key; only the fetch lives here.
+    // SetupGuard has already verified the key; only model loading lives here.
     if (!requested.current) {
       requested.current = true;
-      void fetchModels();
+      void loadModels();
     }
-  }, [fetchModels]);
+  }, [loadModels]);
 
   return (
     <PageScaffold
-      title="选择模型"
-      description="从当前 Key 可访问的模型中选择，接口不支持时可直接输入模型 ID。"
+      title={t("选择模型")}
+      description={t("从当前 Key 可访问的模型中选择，接口不支持时可直接输入模型 ID。")}
       stepper
       onBack={() => navigate("/setup/provider")}
-      primaryLabel="继续"
+      primaryLabel={t("继续")}
       onPrimary={() => navigate("/setup/review")}
       primaryDisabled={!state.model.trim() || state.modelsState === "loading"}
       secondaryAction={
-        <button className="button button-secondary" type="button" onClick={() => void fetchModels()} disabled={state.modelsState === "loading"}>
+        <button className="button button-secondary" type="button" onClick={() => void loadModels()} disabled={state.modelsState === "loading"}>
           <RefreshCw size={15} className={state.modelsState === "loading" ? "spin" : ""} />
-          刷新列表
+          {t("刷新列表")}
         </button>
       }
     >
-      {state.modelsState === "loading" ? <div className="loading-block"><span className="spinner" />正在读取模型列表</div> : null}
+      {state.modelsState === "loading" ? <div className="loading-block"><span className="spinner" />{t("正在读取模型列表")}</div> : null}
       {state.modelsMessage && state.modelsState !== "loading" ? (
         <div className={`notice ${state.modelsState === "success" ? "notice-success" : "notice-warning"}`}>{state.modelsMessage}</div>
       ) : null}
diff --git a/frontend/src/pages/ProfilesPage.test.tsx b/frontend/src/pages/ProfilesPage.test.tsx
index 59c62201..750393c2 100644
--- a/frontend/src/pages/ProfilesPage.test.tsx
+++ b/frontend/src/pages/ProfilesPage.test.tsx
@@ -1,12 +1,15 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { MemoryRouter } from "react-router-dom";
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
+import { api } from "../backend/api";
 import type { ProfileSummary, StatusResponse } from "../types/api";
 import { ProfilesPage } from "./ProfilesPage";
 
+const refreshStatus = vi.fn<() => Promise<void>>();
+
 vi.mock("../state/WizardContext", () => ({
-  useWizard: () => ({ state: mockState, dispatch: vi.fn(), refreshStatus: vi.fn() }),
+  useWizard: () => ({ state: mockState, dispatch: vi.fn(), refreshStatus }),
 }));
 
 let mockState: { status: StatusResponse | null; statusState: string };
@@ -15,7 +18,8 @@ function statusWith(profiles: ProfileSummary[]): StatusResponse {
   return {
     apiVersion: 1,
     platform: { os: "macos", arch: "arm64", shell: "bash" },
-    capabilities: { canInstall: {}, supportedAgentIds: [] },
+    runtimes: [],
+    capabilities: { canInstall: {}, missingRuntime: {}, supportedAgentIds: [] },
     agents: {
       codex: {
         installed: true,
@@ -26,6 +30,7 @@ function statusWith(profiles: ProfileSummary[]): StatusResponse {
         lockedVersion: "1.0.0",
         canInstall: true,
         provider: "ppio",
+        profileId: "team-ppio",
         model: "deepseek/deepseek-v3",
         baseUrl: null,
         updatedAt: null,
@@ -82,42 +87,88 @@ function renderPage(profiles: ProfileSummary[]) {
 }
 
 describe("ProfilesPage", () => {
-  it("lists a template with its provider and model", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    refreshStatus.mockReset();
+    refreshStatus.mockResolvedValue();
+  });
+
+  it("lists public Profile details without returning the key", () => {
     renderPage([profile()]);
     expect(screen.getByText("团队 PPIO")).toBeTruthy();
     expect(screen.getByText(/deepseek\/deepseek-v3/)).toBeTruthy();
-  });
-
-  it("reports only whether a key is held, never the key", () => {
-    // A template can carry a credential; the page may say it exists and
-    // nothing more. There is no API that would return it and none should be
-    // added for display.
-    renderPage([profile({ hasKey: true })]);
     expect(screen.getByText(/已保存密钥/)).toBeTruthy();
-    const markup = document.body.innerHTML;
-    expect(markup).not.toMatch(/sk-[A-Za-z0-9]/);
-    expect(JSON.stringify(localStorage)).not.toMatch(/sk-/);
+    expect(document.body.innerHTML).not.toMatch(/sk-[A-Za-z0-9]/);
   });
 
-  it("distinguishes a template with no key", () => {
-    renderPage([profile({ hasKey: false })]);
-    expect(screen.getByText(/未保存密钥/)).toBeTruthy();
+  it("starts Profile creation from the template manager", () => {
+    renderPage([]);
+    expect(screen.getByText(/还没有 Profile/)).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "新增 Profile" }));
+    expect(screen.getByRole("heading", { name: "配置模板" })).toBeTruthy();
+    expect(screen.getByLabelText("Profile ID")).toBeTruthy();
   });
 
-  it("offers to build a template from a configured Agent when empty", () => {
-    // Matching real order of use: people configure an Agent first and only then
-    // want to reuse that combination.
+  it("creates a Profile with Provider, model, key, and Agents", async () => {
+    const save = vi.spyOn(api, "saveProfile").mockResolvedValue(profile());
     renderPage([]);
-    expect(screen.getByText(/还没有配置模板/)).toBeTruthy();
-    expect(screen.getByRole("button", { name: /从现有 Agent/ })).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "新增 Profile" }));
+    fireEvent.change(screen.getByLabelText("Profile ID"), { target: { value: "team-ppio" } });
+    fireEvent.change(screen.getByLabelText("名称"), { target: { value: "团队 PPIO" } });
+    fireEvent.change(screen.getByLabelText("模型"), { target: { value: "deepseek/deepseek-v3" } });
+    fireEvent.change(screen.getByLabelText("API Key"), { target: { value: "sk-new" } });
+    fireEvent.click(screen.getByLabelText("选择 Codex"));
+    fireEvent.click(screen.getByRole("button", { name: "保存 Profile" }));
+
+    await waitFor(() => expect(save).toHaveBeenCalledWith({
+      id: "team-ppio",
+      label: "团队 PPIO",
+      provider: "ppio",
+      apiBaseUrl: "",
+      apiKey: "sk-new",
+      model: "deepseek/deepseek-v3",
+      configMode: "provider",
+      agentIds: ["codex"],
+    }));
+  });
+
+  it("edits metadata without asking the backend to replace a saved key", async () => {
+    const save = vi.spyOn(api, "saveProfile").mockResolvedValue(profile({ label: "团队默认" }));
+    renderPage([profile()]);
+    fireEvent.click(screen.getByRole("button", { name: "编辑 团队 PPIO" }));
+    expect(screen.getByLabelText("Profile ID").hasAttribute("disabled")).toBe(true);
+    expect(screen.getByText(/留空将保留/)).toBeTruthy();
+    fireEvent.change(screen.getByLabelText("名称"), { target: { value: "团队默认" } });
+    fireEvent.click(screen.getByRole("button", { name: "保存 Profile" }));
+
+    await waitFor(() => expect(save).toHaveBeenCalledWith(expect.objectContaining({
+      id: "team-ppio",
+      label: "团队默认",
+      apiKey: "",
+    })));
   });
 
-  it("lets a template be applied to a specific Agent", () => {
-    // Applying is the whole point of a template. Deletion needs a backend
-    // endpoint that does not exist yet, so it is deliberately absent rather
-    // than present and broken.
+  it("applies one Profile to all of its Agents", async () => {
+    const install = vi.spyOn(api, "install").mockResolvedValue({
+      ok: true,
+      code: 0,
+      results: [{ agent: "codex", status: "configured", retryable: false }],
+      log: "",
+      next: "",
+      probe: null,
+      probes: {},
+    });
     renderPage([profile()]);
-    expect(screen.getByRole("button", { name: /应用到/ })).toBeTruthy();
-    expect(screen.queryByRole("button", { name: /删除/ })).toBeNull();
+    fireEvent.click(screen.getByRole("button", { name: "应用到 Agent" }));
+
+    await waitFor(() => expect(install).toHaveBeenCalledWith(expect.objectContaining({
+      agents: ["codex"],
+      profile_id: "team-ppio",
+      provider: "ppio",
+      api_key: "",
+      model: "deepseek/deepseek-v3",
+      install_agent: true,
+    })));
+    await waitFor(() => expect(screen.getByText(/已应用到 1 个 Agent/)).toBeTruthy());
   });
 });
diff --git a/frontend/src/pages/ProfilesPage.tsx b/frontend/src/pages/ProfilesPage.tsx
index 2bdc0361..914437b1 100644
--- a/frontend/src/pages/ProfilesPage.tsx
+++ b/frontend/src/pages/ProfilesPage.tsx
@@ -1,85 +1,286 @@
-import { KeyRound, Layers, Plus } from "lucide-react";
+import { KeyRound, Layers, Pencil, Play, Plus, Save, X } from "lucide-react";
+import { useState, type FormEvent } from "react";
 import { useNavigate } from "react-router-dom";
 
+import { api, describeError } from "../backend/api";
+import { AgentRow } from "../components/AgentRow";
 import { PageScaffold } from "../components/PageScaffold";
+import { ProviderSegment } from "../components/ProviderSegment";
+import { SecureKeyField } from "../components/SecureKeyField";
+import { useI18n } from "../i18n";
 import { useWizard } from "../state/WizardContext";
+import type { ProfileSummary, ProviderId } from "../types/api";
+
+interface ProfileDraft {
+  id: string;
+  label: string;
+  provider: ProviderId;
+  model: string;
+  agentIds: string[];
+  apiKey: string;
+  hasKey: boolean;
+  originalId: string;
+  originalProvider: ProviderId;
+}
+
+function editDraft(profile: ProfileSummary): ProfileDraft {
+  return {
+    id: profile.id,
+    label: profile.label,
+    provider: profile.provider,
+    model: profile.model || "",
+    agentIds: [...profile.agentIds],
+    apiKey: "",
+    hasKey: profile.hasKey,
+    originalId: profile.id,
+    originalProvider: profile.provider,
+  };
+}
 
 export function ProfilesPage() {
   const navigate = useNavigate();
-  const { state } = useWizard();
+  const { locale, t } = useI18n();
+  const { state, refreshStatus } = useWizard();
   const status = state.status;
+  const [editor, setEditor] = useState<ProfileDraft | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [applying, setApplying] = useState("");
+  const [failure, setFailure] = useState("");
+  const [success, setSuccess] = useState("");
 
   if (!status) {
     return (
-      <PageScaffold title="配置模板">
-        <div className="loading-block"><span className="spinner" />正在读取环境状态</div>
+      <PageScaffold title={t("配置模板")}>
+        <div className="loading-block"><span className="spinner" />{t("正在读取环境状态")}</div>
       </PageScaffold>
     );
   }
 
   const profiles = status.profiles;
+  const configurableAgents = status.catalog.filter((agent) => agent.configMode === "auto");
   const nameOf = (agentId: string) =>
     status.catalog.find((item) => item.id === agentId)?.name || agentId;
-  const configured = Object.entries(status.agents).filter(([, agent]) => agent.provider);
+  const keepsSavedKey = Boolean(
+    editor?.hasKey && editor.originalProvider === editor.provider && !editor.apiKey,
+  );
+  const providerHasKey = Boolean(editor && status.providers[editor.provider]?.has_key);
+  const canSave = Boolean(
+    editor?.id.trim() && editor.label.trim() && editor.model.trim() && editor.agentIds.length
+      && (editor.apiKey || keepsSavedKey || providerHasKey),
+  );
 
-  if (!profiles.length) {
-    return (
-      <PageScaffold
-        title="配置模板"
-        description="把一组 Provider 与模型存成模板，之后可以直接套用到别的 Agent。"
-        primaryLabel={configured.length ? "从现有 Agent 创建" : undefined}
-        onPrimary={configured.length ? () => navigate(`/agents/${configured[0][0]}`) : undefined}
-      >
-        <div className="empty-overview">
-          <Layers size={26} />
-          <strong>还没有配置模板</strong>
-          <span>
-            {configured.length
-              ? "已配置的 Agent 可以直接存为模板，省去重复填写 Provider、模型和密钥。"
-              : "先配置一个 Agent，就可以把那组设置存成模板。"}
-          </span>
-        </div>
-      </PageScaffold>
-    );
-  }
+  const openNew = () => {
+    const provider = status.providers.ppio ? "ppio" : Object.keys(status.providers)[0] || "";
+    setEditor({
+      id: "",
+      label: "",
+      provider,
+      model: "",
+      agentIds: [],
+      apiKey: "",
+      hasKey: false,
+      originalId: "",
+      originalProvider: provider,
+    });
+    setFailure("");
+    setSuccess("");
+  };
+
+  const save = async (event: FormEvent) => {
+    event.preventDefault();
+    if (!editor || !canSave) return;
+    setBusy(true);
+    setFailure("");
+    setSuccess("");
+    try {
+      await api.saveProfile({
+        id: editor.id.trim(),
+        label: editor.label.trim(),
+        provider: editor.provider,
+        apiBaseUrl: "",
+        apiKey: editor.apiKey,
+        model: editor.model.trim(),
+        configMode: "provider",
+        agentIds: editor.agentIds,
+      });
+      await refreshStatus();
+      setEditor(null);
+    } catch (error) {
+      setFailure(describeError(error, t("无法保存 Profile")).message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const apply = async (profile: ProfileSummary) => {
+    if (!profile.model || !profile.agentIds.length) return;
+    setApplying(profile.id);
+    setFailure("");
+    setSuccess("");
+    try {
+      const result = await api.install({
+        agents: profile.agentIds,
+        profile_agents: profile.agentIds,
+        provider: profile.provider,
+        api_base_url: profile.baseUrl || "",
+        api_key: "",
+        model: profile.model,
+        profile_id: profile.id,
+        configure: true,
+        install_agent: true,
+        locked_version: true,
+        skip_test: false,
+      });
+      if (!result.ok) {
+        throw new Error(result.results.find((item) => item.status === "failed")?.message || t("应用 Profile 失败"));
+      }
+      await refreshStatus();
+      setSuccess(t("{name} 已应用到 {count} 个 Agent", { name: profile.label, count: profile.agentIds.length }));
+    } catch (error) {
+      setFailure(describeError(error, t("无法应用 Profile")).message);
+    } finally {
+      setApplying("");
+    }
+  };
 
   return (
-    <PageScaffold title="配置模板" description="套用模板不会改动其他 Agent。">
-      <div className="profile-list">
-        {profiles.map((profile) => (
-          <article className="profile-card" key={profile.id} data-testid={`profile-${profile.id}`}>
-            <header>
-              <strong>{profile.label}</strong>
-              {/* Whether a credential is held, never the credential: there is no
-                  API that returns it and none should be added for display. */}
-              <span className={`profile-key${profile.hasKey ? " has-key" : ""}`}>
-                <KeyRound size={12} aria-hidden="true" />
-                {profile.hasKey ? "已保存密钥" : "未保存密钥"}
-              </span>
-            </header>
-            <p className="profile-target">
-              {status.providers[profile.provider]?.name || profile.provider}
-              <span aria-hidden="true"> · </span>
-              {profile.model || "未指定模型"}
-            </p>
-            {profile.agentIds.length ? (
-              <p className="profile-agents">
-                适用：{profile.agentIds.map(nameOf).join("、")}
-              </p>
-            ) : null}
-            <footer>
-              <button
-                className="button button-secondary"
-                type="button"
-                onClick={() => navigate(`/agents/${profile.agentIds[0] || configured[0]?.[0] || "codex"}?profile=${profile.id}`)}
-              >
-                <Plus size={14} />
-                应用到 Agent
-              </button>
-            </footer>
-          </article>
-        ))}
+    <PageScaffold title={t("配置模板")} description={t("在这里创建 Profile，再将它应用到所选 Agent。")}>
+      <div className="profile-toolbar">
+        <button className="button button-secondary" type="button" onClick={openNew}>
+          <Plus size={15} />
+          {t("新增 Profile")}
+        </button>
       </div>
+
+      {editor ? (
+        <form className="profile-editor" onSubmit={(event) => void save(event)}>
+          <header>
+            <strong>{editor.originalId ? t("编辑 {name}", { name: editor.label || editor.id }) : t("新增 Profile")}</strong>
+            <button className="icon-button" type="button" onClick={() => setEditor(null)} aria-label={t("关闭编辑")} title={t("关闭编辑")}>
+              <X size={16} />
+            </button>
+          </header>
+
+          <div className="profile-editor-grid">
+            <div className="field-stack">
+              <label htmlFor="profile-id">Profile ID</label>
+              <input
+                id="profile-id"
+                value={editor.id}
+                onChange={(event) => setEditor({ ...editor, id: event.target.value })}
+                pattern="[a-z0-9][a-z0-9_-]{0,63}"
+                placeholder={t("例如 team-ppio")}
+                disabled={Boolean(editor.originalId)}
+                required
+              />
+            </div>
+            <div className="field-stack">
+              <label htmlFor="profile-label">{t("名称")}</label>
+              <input id="profile-label" value={editor.label} onChange={(event) => setEditor({ ...editor, label: event.target.value })} placeholder={t("例如 团队 PPIO")} required />
+            </div>
+            <div className="profile-editor-wide">
+              <ProviderSegment
+                value={editor.provider}
+                providers={status.providers}
+                onAdd={() => navigate(`/providers/new?returnTo=${encodeURIComponent("/profiles")}`)}
+                onChange={(provider) => setEditor({ ...editor, provider, apiKey: "" })}
+              />
+            </div>
+            <div className="field-stack profile-editor-wide">
+              <label htmlFor="profile-model">{t("模型")}</label>
+              <input id="profile-model" value={editor.model} onChange={(event) => setEditor({ ...editor, model: event.target.value })} placeholder={t("例如 deepseek/deepseek-v3")} required />
+            </div>
+            <div className="profile-editor-wide">
+              <SecureKeyField value={editor.apiKey} onChange={(apiKey) => setEditor({ ...editor, apiKey })} />
+              {keepsSavedKey ? <p className="profile-key-hint">{t("留空将保留这个 Profile 已保存的 Key。")}</p> : null}
+              {!keepsSavedKey && !editor.apiKey && providerHasKey ? <p className="profile-key-hint">{t("留空将使用 Provider 已保存的 Key。")}</p> : null}
+            </div>
+            <fieldset className="profile-agent-picker profile-editor-wide">
+              <legend>{t("适用 Agent")}</legend>
+              <div className="agent-list">
+                {configurableAgents.map((agent) => (
+                  <AgentRow
+                    key={agent.id}
+                    agent={agent}
+                    status={status.agents[agent.id]}
+                    selected={editor.agentIds.includes(agent.id)}
+                    onToggle={() => setEditor({
+                      ...editor,
+                      agentIds: editor.agentIds.includes(agent.id)
+                        ? editor.agentIds.filter((id) => id !== agent.id)
+                        : [...editor.agentIds, agent.id],
+                    })}
+                  />
+                ))}
+              </div>
+            </fieldset>
+          </div>
+
+          <footer>
+            <button className="button button-secondary" type="button" onClick={() => setEditor(null)}>{t("取消")}</button>
+            <button className="button button-primary" type="submit" disabled={!canSave || busy}>
+              <Save size={15} />
+              {busy ? t("保存中") : t("保存 Profile")}
+            </button>
+          </footer>
+        </form>
+      ) : null}
+
+      {failure ? <p className="agent-manage-error">{failure}</p> : null}
+      {success ? <div className="agent-manage-applied"><strong>{t("应用完成")}</strong><span>{success}</span></div> : null}
+
+      {!profiles.length && !editor ? (
+        <div className="empty-overview">
+          <Layers size={26} />
+          <strong>{t("还没有 Profile")}</strong>
+          <span>{t("新建一个 Profile，保存 Provider、模型、Key 和适用 Agent。")}</span>
+        </div>
+      ) : (
+        <div className="profile-list">
+          {profiles.map((profile) => {
+            const canApply = Boolean(
+              profile.model && profile.agentIds.length
+                && (profile.hasKey || status.providers[profile.provider]?.has_key),
+            );
+            return (
+              <article className="profile-card" key={profile.id} data-testid={`profile-${profile.id}`}>
+                <header>
+                  <span className="profile-title"><strong>{profile.label}</strong><small>{profile.id}</small></span>
+                  <span className="profile-card-actions">
+                    <span className={`profile-key${profile.hasKey ? " has-key" : ""}`}>
+                      <KeyRound size={12} aria-hidden="true" />
+                      {profile.hasKey ? t("已保存密钥") : t("未保存密钥")}
+                    </span>
+                    <button className="icon-button" type="button" onClick={() => { setEditor(editDraft(profile)); setFailure(""); setSuccess(""); }} aria-label={t("编辑 {name}", { name: profile.label })} title={t("编辑")}>
+                      <Pencil size={14} />
+                    </button>
+                  </span>
+                </header>
+                <p className="profile-target">
+                  {status.providers[profile.provider]?.name || profile.provider}
+                  <span aria-hidden="true"> · </span>
+                  {profile.model || t("未指定模型")}
+                </p>
+                <p className="profile-agents">
+                  {t("适用：{agents}", { agents: profile.agentIds.length ? profile.agentIds.map(nameOf).join(locale === "en" ? ", " : "、") : t("未选择 Agent") })}
+                </p>
+                <footer>
+                  <button
+                    className="button button-secondary"
+                    type="button"
+                    onClick={() => void apply(profile)}
+                    disabled={!canApply || Boolean(applying)}
+                    title={canApply ? t("安装缺失的 Agent 并应用此 Profile") : t("请先补全模型、Agent 和 Key")}
+                  >
+                    <Play size={14} />
+                    {applying === profile.id ? t("应用中") : t("应用到 Agent")}
+                  </button>
+                </footer>
+              </article>
+            );
+          })}
+        </div>
+      )}
     </PageScaffold>
   );
 }
diff --git a/frontend/src/pages/ProviderKeyPage.test.tsx b/frontend/src/pages/ProviderKeyPage.test.tsx
new file mode 100644
index 00000000..2fbc7f94
--- /dev/null
+++ b/frontend/src/pages/ProviderKeyPage.test.tsx
@@ -0,0 +1,45 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+import { describe, expect, it, vi } from "vitest";
+
+import { api } from "../backend/api";
+import { initialWizardState, wizardReducer, type WizardAction, type WizardState } from "../state/wizardReducer";
+import { ProviderKeyPage } from "./ProviderKeyPage";
+
+let state: WizardState;
+const keyRef = { current: "test-key" };
+const dispatch = vi.fn((action: WizardAction) => {
+  state = wizardReducer(state, action);
+});
+
+vi.mock("../state/WizardContext", () => ({
+  useWizard: () => ({
+    state,
+    dispatch,
+    secret: { keyRef, setApiKey: vi.fn(), clearApiKey: vi.fn() },
+  }),
+}));
+
+describe("ProviderKeyPage", () => {
+  it("uses a custom model name for the connection test", async () => {
+    state = { ...initialWizardState, hasApiKey: true };
+    dispatch.mockClear();
+    const probe = vi.spyOn(api, "probe").mockResolvedValue({
+      ok: true,
+      reachable: true,
+      status: 200,
+      message: "ok",
+      error_code: null,
+      retryable: false,
+    });
+    const page = render(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);
+
+    fireEvent.change(screen.getByLabelText("自定义模型名称（可选）"), { target: { value: "vendor/custom-model" } });
+    page.rerender(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);
+    fireEvent.click(screen.getByRole("button", { name: "测试连接" }));
+
+    await waitFor(() =>
+      expect(probe).toHaveBeenCalledWith(expect.objectContaining({ model: "vendor/custom-model", apiKey: "test-key" })),
+    );
+  });
+});
diff --git a/frontend/src/pages/ProviderKeyPage.tsx b/frontend/src/pages/ProviderKeyPage.tsx
index ee53ce2a..2ba48c64 100644
--- a/frontend/src/pages/ProviderKeyPage.tsx
+++ b/frontend/src/pages/ProviderKeyPage.tsx
@@ -1,26 +1,41 @@
 import { ExternalLink, FlaskConical, Link2 } from "lucide-react";
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 import { useNavigate } from "react-router-dom";
 
-import { api, describeError } from "../api/client";
+import { api, describeError } from "../backend/api";
 import { ConnectionStatus } from "../components/ConnectionStatus";
 import { PageScaffold } from "../components/PageScaffold";
 import { ProviderSegment } from "../components/ProviderSegment";
 import { SecureKeyField } from "../components/SecureKeyField";
+import { useI18n } from "../i18n";
 import { useWizard } from "../state/WizardContext";
 import { PROTOCOL_LABELS } from "../types/api";
 import type { ProtocolId, ProviderId } from "../types/api";
 
 export function ProviderKeyPage() {
   const navigate = useNavigate();
+  const { t } = useI18n();
   const { state, dispatch, secret } = useWizard();
-  const providerMeta = state.provider === "custom" ? null : state.status?.providers[state.provider];
-  const apiBaseUrl = state.provider === "custom" ? state.customBaseUrl : providerMeta?.base_url || "";
-  const canProbe = state.hasApiKey && (state.provider !== "custom" || Boolean(state.customBaseUrl.trim()));
+  const providerMeta = state.status?.providers[state.provider];
+  const apiBaseUrl = providerMeta?.base_url || "";
+  const canProbe = state.hasApiKey;
   // Continuing requires a successful probe, not just a non-empty key: a wrong
   // key must not reach the model step. canProbe stays separate so the test
   // button remains clickable while the verdict is still outstanding.
   const canContinue = canProbe && state.connectionState === "success";
+
+  useEffect(() => {
+    if (!providerMeta?.has_key) return;
+    let active = true;
+    void api.getProvider(state.provider)
+      .then((entry) => {
+        if (active) secret.setApiKey(entry.api_key);
+      })
+      .catch((error) => {
+        if (active) dispatch({ type: "CONNECTION_FAILED", failure: describeError(error, t("无法读取已保存的 API Key")) });
+      });
+    return () => { active = false; };
+  }, [dispatch, providerMeta?.has_key, secret.setApiKey, state.provider]);
   // The selected Agents decide which protocols get tested; a model that serves
   // Chat Completions may still refuse Responses, so do not imply a single one.
   const protocols = useMemo(() => {
@@ -39,6 +54,7 @@ export function ProviderKeyPage() {
   }, [apiBaseUrl, protocols]);
 
   const changeProvider = (provider: ProviderId) => {
+    secret.clearApiKey();
     dispatch({ type: "SET_PROVIDER", value: provider });
   };
 
@@ -47,78 +63,84 @@ export function ProviderKeyPage() {
     try {
       const result = await api.probe({
         provider: state.provider,
-        apiBaseUrl: state.provider === "custom" ? state.customBaseUrl : "",
+        apiBaseUrl: "",
         apiKey: secret.keyRef.current,
-        // Empty before the model step; the backend picks its probe default.
+        // A user-supplied ID lets providers without model discovery validate
+        // the model that will actually be configured.
         model: state.model,
         agents: state.selectedAgentIds,
       });
       dispatch({ type: "CONNECTION_RESULT", result });
     } catch (error) {
-      dispatch({ type: "CONNECTION_FAILED", failure: describeError(error, "连接测试失败") });
+      dispatch({ type: "CONNECTION_FAILED", failure: describeError(error, t("连接测试失败")) });
     }
   };
 
   const openRegistration = async () => {
-    if (state.provider === "custom") return;
+    if (!providerMeta?.home) return;
     try {
       await api.openRegister(state.provider, state.selectedAgentIds);
     } catch (error) {
-      dispatch({ type: "CONNECTION_FAILED", failure: describeError(error, "无法打开注册页面") });
+      dispatch({ type: "CONNECTION_FAILED", failure: describeError(error, t("无法打开注册页面")) });
     }
   };
 
   return (
     <PageScaffold
-      title="连接模型服务"
-      description="Key 不会进入日志、URL 或前端持久化状态。"
+      title={t("连接模型服务")}
+      description={t("Key 不会进入日志、URL 或前端持久化状态。")}
       stepper
       onBack={() => navigate("/setup/mode")}
-      primaryLabel="继续选择模型"
+      primaryLabel={t("继续选择模型")}
       onPrimary={() => navigate("/setup/model")}
       primaryDisabled={!canContinue || state.connectionState === "loading"}
       footerNote={endpoint ? <span className="endpoint-note"><Link2 size={14} />{endpoint}</span> : undefined}
     >
-      <ProviderSegment value={state.provider} onChange={changeProvider} />
+      <ProviderSegment
+        value={state.provider}
+        providers={state.status?.providers ?? {}}
+        onAdd={() => navigate(`/providers/new?returnTo=${encodeURIComponent("/setup/provider")}`)}
+        onChange={changeProvider}
+      />
 
       <div className="provider-form">
-        {state.provider === "custom" ? (
-          <div className="field-stack">
-            <label htmlFor="custom-base-url">Base URL</label>
-            <input
-              id="custom-base-url"
-              className="text-field"
-              value={state.customBaseUrl}
-              onChange={(event) => dispatch({ type: "SET_CUSTOM_BASE", value: event.target.value })}
-              placeholder="https://models.example.com/openai"
-              inputMode="url"
-            />
-            <small>支持 HTTP/HTTPS，包括用户主动配置的本机地址；URL 不能包含账号或密码。</small>
+        <div className="provider-identity-row">
+          <div>
+            <strong>{providerMeta?.name}</strong>
+            <span>{providerMeta?.base_url}</span>
           </div>
-        ) : (
-          <div className="provider-identity-row">
-            <div>
-              <strong>{providerMeta?.name}</strong>
-              <span>{providerMeta?.base_url}</span>
-            </div>
+          {providerMeta?.home ? (
             <button className="button button-secondary" type="button" onClick={() => void openRegistration()}>
               <ExternalLink size={15} />
-              注册并获取 Key
+              {t("注册并获取 Key")}
             </button>
-          </div>
-        )}
+          ) : null}
+        </div>
+
+        <div className="field-stack">
+          <label htmlFor="provider-model">{t("自定义模型名称（可选）")}</label>
+          <input
+            id="provider-model"
+            className="text-field"
+            value={state.model}
+            onChange={(event) => dispatch({ type: "SET_MODEL", value: event.target.value })}
+            placeholder={t("例如 deepseek/deepseek-v3")}
+            spellCheck={false}
+          />
+          <small>{t("填写后将用此模型测试连接；留空时自动选择。")}</small>
+        </div>
 
         <SecureKeyField value={secret.keyRef.current} onChange={secret.setApiKey} />
 
         <div className="connection-row">
           <button className="button button-secondary" type="button" onClick={() => void testConnection()} disabled={!canProbe || state.connectionState === "loading"}>
             <FlaskConical size={16} />
-            测试连接
+            {t("测试连接")}
           </button>
           <ConnectionStatus state={state.connectionState} result={state.connection} />
         </div>
         {canProbe && state.connectionState === "idle" && (
-          <small>连接测试通过后才能继续选择模型。</small>
+          <small>{t("连接测试通过后才能继续选择模型。")}</small>
         )}
       </div>
     </PageScaffold>
diff --git a/frontend/src/pages/ProvidersPage.test.tsx b/frontend/src/pages/ProvidersPage.test.tsx
index b0940dc9..21d6d455 100644
--- a/frontend/src/pages/ProvidersPage.test.tsx
+++ b/frontend/src/pages/ProvidersPage.test.tsx
@@ -1,7 +1,8 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { MemoryRouter } from "react-router-dom";
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
+import { api } from "../backend/api";
 import type { StatusResponse } from "../types/api";
 import { ProvidersPage } from "./ProvidersPage";
 
@@ -15,7 +16,8 @@ function statusWith(agents: Record<string, string | null>): StatusResponse {
   return {
     apiVersion: 1,
     platform: { os: "macos", arch: "arm64", shell: "bash" },
-    capabilities: { canInstall: {}, supportedAgentIds: [] },
+    runtimes: [],
+    capabilities: { canInstall: {}, missingRuntime: {}, supportedAgentIds: [] },
     agents: Object.fromEntries(
       Object.entries(agents).map(([id, provider]) => [
         id,
@@ -28,6 +30,7 @@ function statusWith(agents: Record<string, string | null>): StatusResponse {
           lockedVersion: "1.0.0",
           canInstall: true,
           provider,
+          profileId: null,
           model: provider ? "some-model" : null,
           baseUrl: null,
           updatedAt: null,
@@ -72,6 +75,8 @@ function renderPage(agents: Record<string, string | null>) {
 }
 
 describe("ProvidersPage", () => {
+  afterEach(() => vi.restoreAllMocks());
+
   it("lists each Provider with its endpoint", () => {
     renderPage({ codex: "ppio" });
     expect(screen.getByText("PPIO")).toBeTruthy();
@@ -94,10 +99,57 @@ describe("ProvidersPage", () => {
     expect(screen.getByTestId("provider-novita").textContent).toMatch(/暂无/);
   });
 
-  it("states that a custom endpoint is the user's responsibility", () => {
-    // ADR-003 puts protocol compatibility on the user for Custom; the UI has to
+  it("states that a user Provider is the user's responsibility", () => {
+    // ADR-003 puts protocol compatibility on the user; the UI has to
     // say it rather than leave it in a document.
     renderPage({ codex: "ppio" });
-    expect(screen.getByText(/自定义/)).toBeTruthy();
+    expect(screen.getByText(/用户 Provider/)).toBeTruthy();
+  });
+
+  it("loads the saved API key when editing and sends updates", async () => {
+    const entry = {
+      id: "ppio", name: "PPIO", home: "https://ppio.com/", base_url: "https://api.ppio.com/openai",
+      anthropic_base_url: "https://api.ppio.com/anthropic", api_key: "sk-saved", built_in: true,
+    };
+    vi.spyOn(api, "getProvider").mockResolvedValue(entry);
+    const save = vi.spyOn(api, "saveProvider").mockResolvedValue(entry);
+    renderPage({ codex: "ppio" });
+
+    fireEvent.click(screen.getByRole("button", { name: "编辑 PPIO" }));
+    await waitFor(() => expect(screen.getByLabelText("API Key")).toHaveValue("sk-saved"));
+    fireEvent.change(screen.getByLabelText("名称"), { target: { value: "PPIO Cloud" } });
+    fireEvent.click(screen.getByRole("button", { name: /^保存$/ }));
+
+    await waitFor(() => expect(save).toHaveBeenCalledWith(expect.objectContaining({ id: "ppio", name: "PPIO Cloud", api_key: "sk-saved" })));
+  });
+
+  it("adds a Provider from the management page", async () => {
+    const save = vi.spyOn(api, "saveProvider").mockResolvedValue({
+      id: "acme", name: "Acme", home: "", base_url: "https://api.acme.test",
+      anthropic_base_url: "", api_key: "sk-acme", built_in: false,
+    });
+    renderPage({ codex: null });
+    fireEvent.click(screen.getByRole("button", { name: "新增 Provider" }));
+    fireEvent.change(screen.getByLabelText("Provider ID"), { target: { value: "acme" } });
+    fireEvent.change(screen.getByLabelText("名称"), { target: { value: "Acme" } });
+    fireEvent.change(screen.getByLabelText("OpenAI 兼容 Base URL"), { target: { value: "https://api.acme.test" } });
+    fireEvent.change(screen.getByLabelText("API Key"), { target: { value: "sk-acme" } });
+    fireEvent.click(screen.getByRole("button", { name: /^保存$/ }));
+    await waitFor(() => expect(save).toHaveBeenCalledWith(expect.objectContaining({ id: "acme", base_url: "https://api.acme.test", api_key: "sk-acme" })));
+  });
+
+  it("deletes a user Provider", async () => {
+    renderPage({ codex: null });
+    if (!mockState.status) throw new Error("missing status");
+    mockState.status.providers.acme = { name: "Acme", home: "", base_url: "https://api.acme.test", custom: true };
+    vi.spyOn(window, "confirm").mockReturnValue(true);
+    const remove = vi.spyOn(api, "deleteProvider").mockResolvedValue();
+    render(
+      <MemoryRouter>
+        <ProvidersPage />
+      </MemoryRouter>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "删除 Acme" }));
+    await waitFor(() => expect(remove).toHaveBeenCalledWith("acme"));
   });
 });
diff --git a/frontend/src/pages/ProvidersPage.tsx b/frontend/src/pages/ProvidersPage.tsx
index 59576ac0..7b9cc74d 100644
--- a/frontend/src/pages/ProvidersPage.tsx
+++ b/frontend/src/pages/ProvidersPage.tsx
@@ -1,16 +1,89 @@
-import { ExternalLink } from "lucide-react";
+import { ExternalLink, KeyRound, Pencil, Plus, Save, Trash2, X } from "lucide-react";
+import { useState, type FormEvent } from "react";
+import { useNavigate, useSearchParams } from "react-router-dom";
 
+import { api, describeError } from "../backend/api";
 import { PageScaffold } from "../components/PageScaffold";
+import { SecureKeyField } from "../components/SecureKeyField";
+import { useI18n } from "../i18n";
 import { useWizard } from "../state/WizardContext";
+import type { ProviderEntry } from "../types/api";
 
-export function ProvidersPage() {
-  const { state } = useWizard();
+const emptyProvider: ProviderEntry = {
+  id: "",
+  name: "",
+  home: "",
+  base_url: "",
+  anthropic_base_url: "",
+  api_key: "",
+  built_in: false,
+};
+
+export function ProvidersPage({ create = false }: { create?: boolean }) {
+  const navigate = useNavigate();
+  const { t } = useI18n();
+  const [searchParams] = useSearchParams();
+  const { state, refreshStatus } = useWizard();
   const status = state.status;
+  const [editor, setEditor] = useState<ProviderEntry | null>(create ? { ...emptyProvider } : null);
+  const [busy, setBusy] = useState(false);
+  const [failure, setFailure] = useState("");
+  const requestedReturn = searchParams.get("returnTo");
+  const returnTo = requestedReturn?.startsWith("/") && !requestedReturn.startsWith("//") ? requestedReturn : "/providers";
+
+  const closeEditor = () => {
+    if (create) navigate(returnTo);
+    else setEditor(null);
+  };
+
+  const edit = async (providerId: string) => {
+    setBusy(true);
+    setFailure("");
+    try {
+      setEditor(await api.getProvider(providerId));
+    } catch (error) {
+      setFailure(describeError(error, t("无法读取 Provider")).message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const save = async (event: FormEvent) => {
+    event.preventDefault();
+    if (!editor) return;
+    setBusy(true);
+    setFailure("");
+    try {
+      await api.saveProvider(editor);
+      await refreshStatus();
+      if (create) navigate(returnTo);
+      else setEditor(null);
+    } catch (error) {
+      setFailure(describeError(error, t("无法保存 Provider")).message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const remove = async (providerId: string, name: string) => {
+    if (!window.confirm(t("删除 Provider“{name}”？", { name }))) return;
+    setBusy(true);
+    setFailure("");
+    try {
+      await api.deleteProvider(providerId);
+      if (editor?.id === providerId) setEditor(null);
+      await refreshStatus();
+    } catch (error) {
+      setFailure(describeError(error, t("无法删除 Provider")).message);
+    } finally {
+      setBusy(false);
+    }
+  };
 
   if (!status) {
     return (
-      <PageScaffold title="Provider">
-        <div className="loading-block"><span className="spinner" />正在读取环境状态</div>
+      <PageScaffold title={create ? t("新增 Provider") : "Provider"}>
+        <div className="loading-block"><span className="spinner" />{t("正在读取环境状态")}</div>
       </PageScaffold>
     );
   }
@@ -19,56 +92,117 @@ export function ProvidersPage() {
     status.catalog.find((item) => item.id === agentId)?.name || agentId;
 
   return (
-    <PageScaffold title="Provider" description="内置模型服务与当前指向它们的 Agent。">
-      <div className="provider-list">
+    <PageScaffold title={create ? t("新增 Provider") : "Provider"} description={t("管理模型服务、端点与本机保存的 API Key。")}>
+      {!create ? (
+        <div className="provider-toolbar">
+          <button className="button button-secondary" type="button" onClick={() => { setEditor({ ...emptyProvider }); setFailure(""); }}>
+            <Plus size={15} />
+            {t("新增 Provider")}
+          </button>
+        </div>
+      ) : null}
+
+      {editor ? (
+        <form className="provider-editor" onSubmit={(event) => void save(event)}>
+          <header>
+            <strong>{editor.id ? t("编辑 {name}", { name: editor.name || editor.id }) : t("新增 Provider")}</strong>
+            <button className="icon-button" type="button" onClick={closeEditor} aria-label={t("关闭编辑")} title={t("关闭编辑")}>
+              <X size={16} />
+            </button>
+          </header>
+          <div className="provider-editor-grid">
+            <div className="field-stack">
+              <label htmlFor="provider-id">Provider ID</label>
+              <input
+                id="provider-id"
+                value={editor.id}
+                onChange={(event) => setEditor({ ...editor, id: event.target.value })}
+                pattern="[a-z0-9][a-z0-9-]{0,63}"
+                placeholder={t("例如 siliconflow")}
+                disabled={editor.built_in}
+                required
+              />
+            </div>
+            <div className="field-stack">
+              <label htmlFor="provider-name">{t("名称")}</label>
+              <input id="provider-name" value={editor.name} onChange={(event) => setEditor({ ...editor, name: event.target.value })} required />
+            </div>
+            <div className="field-stack provider-editor-wide">
+              <label htmlFor="provider-base-url">{t("OpenAI 兼容 Base URL")}</label>
+              <input id="provider-base-url" type="url" value={editor.base_url} onChange={(event) => setEditor({ ...editor, base_url: event.target.value })} placeholder="https://api.example.com/openai" required />
+            </div>
+            <div className="field-stack provider-editor-wide">
+              <label htmlFor="provider-anthropic-url">{t("Anthropic 兼容 Base URL（可选）")}</label>
+              <input id="provider-anthropic-url" type="url" value={editor.anthropic_base_url} onChange={(event) => setEditor({ ...editor, anthropic_base_url: event.target.value })} placeholder="https://api.example.com/anthropic" />
+            </div>
+            <div className="field-stack provider-editor-wide">
+              <label htmlFor="provider-home">{t("官网（可选）")}</label>
+              <input id="provider-home" type="url" value={editor.home} onChange={(event) => setEditor({ ...editor, home: event.target.value })} placeholder="https://example.com/" />
+            </div>
+            <div className="provider-editor-wide">
+              <SecureKeyField value={editor.api_key} onChange={(value) => setEditor({ ...editor, api_key: value })} />
+            </div>
+          </div>
+          <footer>
+            <button className="button button-secondary" type="button" onClick={closeEditor}>{t("取消")}</button>
+            <button className="button button-primary" type="submit" disabled={busy}>
+              <Save size={15} />
+              {busy ? t("保存中") : t("保存")}
+            </button>
+          </footer>
+        </form>
+      ) : null}
+
+      {failure ? <p className="agent-manage-error">{failure}</p> : null}
+
+      {!create ? <div className="provider-list">
         {Object.entries(status.providers).map(([providerId, meta]) => {
-          // Reverse lookup from the per-Agent bindings: this is what answers
-          // "which Agents stop working if this endpoint does".
           const users = Object.entries(status.agents)
             .filter(([, agent]) => agent.provider === providerId)
             .map(([agentId]) => agentId);
           return (
             <article className="provider-card" key={providerId} data-testid={`provider-${providerId}`}>
               <header>
-                <strong>{meta.name}</strong>
-                <a className="provider-link" href={meta.home} target="_blank" rel="noreferrer">
-                  <ExternalLink size={13} aria-hidden="true" />
-                  官网
-                </a>
+                <span className="provider-title">
+                  <strong>{meta.name}</strong>
+                  {meta.custom ? <small>{t("用户添加")}</small> : null}
+                </span>
+                <span className="provider-card-actions">
+                  {meta.home ? (
+                    <a className="provider-link" href={meta.home} target="_blank" rel="noreferrer">
+                      <ExternalLink size={13} aria-hidden="true" />{t("官网")}
+                    </a>
+                  ) : null}
+                  <button className="icon-button" type="button" onClick={() => void edit(providerId)} aria-label={t("编辑 {name}", { name: meta.name })} title={t("编辑")}>
+                    <Pencil size={14} />
+                  </button>
+                  {meta.custom ? (
+                    <button className="icon-button is-danger" type="button" onClick={() => void remove(providerId, meta.name)} aria-label={t("删除 {name}", { name: meta.name })} title={t("删除")}>
+                      <Trash2 size={14} />
+                    </button>
+                  ) : null}
+                </span>
               </header>
               <dl className="provider-endpoints">
-                <div>
-                  <dt>OpenAI 兼容</dt>
-                  <dd>{meta.base_url}</dd>
-                </div>
-                {meta.anthropic_base_url ? (
-                  <div>
-                    <dt>Anthropic 兼容</dt>
-                    <dd>{meta.anthropic_base_url}</dd>
-                  </div>
-                ) : null}
+                <div><dt>{t("OpenAI 兼容")}</dt><dd>{meta.base_url}</dd></div>
+                {meta.anthropic_base_url ? <div><dt>{t("Anthropic 兼容")}</dt><dd>{meta.anthropic_base_url}</dd></div> : null}
               </dl>
               <footer>
                 {users.length ? (
                   <span className="provider-users">
-                    {users.map((agentId) => (
-                      <span className="provider-user-chip" key={agentId}>
-                        {nameOf(agentId)}
-                      </span>
-                    ))}
+                    {users.map((agentId) => <span className="provider-user-chip" key={agentId}>{nameOf(agentId)}</span>)}
                   </span>
-                ) : (
-                  <span className="provider-users is-empty">暂无 Agent 使用</span>
-                )}
+                ) : <span className="provider-users is-empty">{t("暂无 Agent 使用")}</span>}
+                <span className={`provider-key-state${meta.has_key ? " has-key" : ""}`}>
+                  <KeyRound size={12} />{meta.has_key ? t("已保存 Key") : t("未保存 Key")}
+                </span>
               </footer>
             </article>
           );
         })}
-      </div>
+      </div> : null}
 
-      <p className="provider-note">
-        也可以为单个 Agent 填写自定义 Base URL。自定义端点的协议兼容性由你自己保证，OneAgent 不会为它降级或改写请求。
-      </p>
+      {!create ? <p className="provider-note">{t("用户 Provider 的协议兼容性由你自己保证，OneAgent 不会为它降级或改写请求。")}</p> : null}
     </PageScaffold>
   );
 }
diff --git a/frontend/src/pages/ReviewPage.tsx b/frontend/src/pages/ReviewPage.tsx
index 6ead489a..2b36414a 100644
--- a/frontend/src/pages/ReviewPage.tsx
+++ b/frontend/src/pages/ReviewPage.tsx
@@ -4,10 +4,12 @@ import { useNavigate } from "react-router-dom";
 
 import { PageScaffold } from "../components/PageScaffold";
 import { ReviewGroup, ReviewRow } from "../components/ReviewGroup";
+import { useI18n } from "../i18n";
 import { useWizard } from "../state/WizardContext";
 
 export function ReviewPage() {
   const navigate = useNavigate();
+  const { t } = useI18n();
   const { state, dispatch } = useWizard();
 
   const startActivation = () => {
@@ -26,48 +28,48 @@ export function ReviewPage() {
   );
   const automatic = selectedCatalog.filter((agent) => agent.configMode === "auto");
   const guideOnly = selectedCatalog.filter((agent) => agent.guideOnly);
-  const providerName = state.configMode === "provider" ? state.status?.providers[state.provider]?.name || "自定义" : "已有账号 / 本机配置";
+  const providerName = state.configMode === "provider" ? state.status?.providers[state.provider]?.name || state.provider : t("已有账号 / 本机配置");
 
   return (
     <PageScaffold
-      title="确认激活"
-      description="核对安装、配置和备份范围。API Key 不会显示在此页。"
+      title={t("确认激活")}
+      description={t("核对安装、配置和备份范围。API Key 不会显示在此页。")}
       stepper
       onBack={() => navigate(state.configMode === "provider" ? "/setup/model" : "/setup/mode")}
-      primaryLabel="开始激活"
+      primaryLabel={t("开始激活")}
       onPrimary={startActivation}
-      footerNote={<span className="secure-note"><ShieldCheck size={15} />覆盖前会自动创建时间戳备份</span>}
+      footerNote={<span className="secure-note"><ShieldCheck size={15} />{t("覆盖前会自动创建时间戳备份")}</span>}
     >
       <div className="review-columns">
-        <ReviewGroup title="将处理">
+        <ReviewGroup title={t("将处理")}>
           {selectedCatalog.map((agent) => (
             <ReviewRow
               key={agent.id}
               label={agent.name}
-              value={state.status?.agents[agent.id]?.installed ? "检测并配置" : state.installMissingAgents && !agent.guideOnly ? "安装并配置" : agent.guideOnly ? "显示引导" : "只写配置"}
+              value={state.status?.agents[agent.id]?.installed ? t("检测并配置") : state.installMissingAgents && !agent.guideOnly ? t("安装并配置") : agent.guideOnly ? t("显示引导") : t("只写配置")}
             />
           ))}
         </ReviewGroup>
 
-        <ReviewGroup title="模型服务">
-          <ReviewRow label="配置方式" value={providerName} />
-          {state.configMode === "provider" ? <ReviewRow label="模型" value={state.model} /> : null}
+        <ReviewGroup title={t("模型服务")}>
+          <ReviewRow label={t("配置方式")} value={providerName} />
+          {state.configMode === "provider" ? <ReviewRow label={t("模型")} value={state.model} /> : null}
           {state.configMode === "provider" ? (
             <ReviewRow
               label="Base URL"
-              value={state.provider === "custom" ? state.customBaseUrl : state.status?.providers[state.provider]?.base_url || ""}
+              value={state.status?.providers[state.provider]?.base_url || ""}
             />
           ) : null}
         </ReviewGroup>
 
-        <ReviewGroup title="本地写入">
+        <ReviewGroup title={t("本地写入")}>
           {state.configMode === "provider"
             ? automatic.map((agent) => (
-                <ReviewRow key={agent.id} label={agent.name} value={state.status?.paths[`${agent.id}_config`] || "由 Agent 官方配置合约决定"} />
+                <ReviewRow key={agent.id} label={agent.name} value={state.status?.paths[`${agent.id}_config`] || t("由 Agent 官方配置合约决定")} />
               ))
-            : <ReviewRow label="模型配置" value="跳过，不覆盖已有设置" muted />}
-          <ReviewRow label="环境摘要" value={state.status?.paths.profile || "~/.oneagent/profile.json"} />
-          {guideOnly.length ? <ReviewRow label="仅引导项目" value={`${guideOnly.length} 个，不写私有配置`} muted /> : null}
+            : <ReviewRow label={t("模型配置")} value={t("跳过，不覆盖已有设置")} muted />}
+          <ReviewRow label={t("环境摘要")} value={state.status?.paths.profile || "~/.oneagent/profile.json"} />
+          {guideOnly.length ? <ReviewRow label={t("仅引导项目")} value={t("{count} 个，不写私有配置", { count: guideOnly.length })} muted /> : null}
         </ReviewGroup>
       </div>
     </PageScaffold>
diff --git a/frontend/src/state/WizardContext.test.tsx b/frontend/src/state/WizardContext.test.tsx
index b632b1a2..23e314e5 100644
--- a/frontend/src/state/WizardContext.test.tsx
+++ b/frontend/src/state/WizardContext.test.tsx
@@ -2,14 +2,15 @@ import { act, renderHook, waitFor } from "@testing-library/react";
 import type { PropsWithChildren } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { api } from "../api/client";
+import { api } from "../backend/api";
 import type { StatusResponse } from "../types/api";
 import { useWizard, WizardProvider } from "./WizardContext";
 
 const status = {
   apiVersion: 1,
   platform: { os: "linux", arch: "x64", shell: "bash" },
-  capabilities: { canInstall: {}, supportedAgentIds: [] },
+  runtimes: [],
+  capabilities: { canInstall: {}, missingRuntime: {}, supportedAgentIds: [] },
   agents: {},
   catalog: [],
   groups: [],
diff --git a/frontend/src/state/WizardContext.tsx b/frontend/src/state/WizardContext.tsx
index 2bf7b76d..3169271e 100644
--- a/frontend/src/state/WizardContext.tsx
+++ b/frontend/src/state/WizardContext.tsx
@@ -11,7 +11,8 @@ import {
   useRef,
 } from "react";
 
-import { api, describeError } from "../api/client";
+import { api, describeError } from "../backend/api";
+import { useI18n } from "../i18n";
 import { initialWizardState, wizardReducer, type WizardAction, type WizardState } from "./wizardReducer";
 
 interface SecretStore {
@@ -30,6 +31,7 @@ interface WizardContextValue {
 const WizardContext = createContext<WizardContextValue | null>(null);
 
 export function WizardProvider({ children }: PropsWithChildren) {
+  const { t } = useI18n();
   const [state, dispatch] = useReducer(wizardReducer, initialWizardState);
   const keyRef = useRef("");
 
@@ -48,9 +50,9 @@ export function WizardProvider({ children }: PropsWithChildren) {
     try {
       dispatch({ type: "STATUS_LOADED", status: await api.status() });
     } catch (error) {
-      dispatch({ type: "STATUS_FAILED", message: describeError(error, "无法读取本机状态").message });
+      dispatch({ type: "STATUS_FAILED", message: describeError(error, t("无法读取本机状态")).message });
     }
-  }, []);
+  }, [t]);
 
   useEffect(() => {
     void refreshStatus();
diff --git a/frontend/src/state/wizardReducer.test.ts b/frontend/src/state/wizardReducer.test.ts
index 9e3a1423..56f361ff 100644
--- a/frontend/src/state/wizardReducer.test.ts
+++ b/frontend/src/state/wizardReducer.test.ts
@@ -6,7 +6,8 @@ import { initialWizardState, wizardReducer, type WizardState } from "./wizardRed
 const status = {
   apiVersion: 1,
   platform: { os: "linux", arch: "x64", shell: "bash" },
-  capabilities: { canInstall: {}, supportedAgentIds: [] },
+  runtimes: [],
+  capabilities: { canInstall: {}, missingRuntime: {}, supportedAgentIds: [] },
   agents: {},
   catalog: [],
   groups: [],
@@ -64,13 +65,11 @@ describe("wizardReducer", () => {
     expect(state.connection).toBeNull();
     expect(state.models).toEqual([]);
     expect(state.model).toBe("");
-    state = wizardReducer(state, { type: "SET_CUSTOM_BASE", value: "http://127.0.0.1:9000" });
-    expect(state.customBaseUrl).toContain("127.0.0.1");
     state = wizardReducer(state, { type: "SET_HAS_API_KEY", value: false });
     expect(state.connectionState).toBe("idle");
   });
 
-  it("invalidates a stale probe verdict whenever the key changes", () => {
+  it("invalidates a stale probe verdict whenever the key or model changes", () => {
     // The reducer only sees the non-empty boolean (the secret stays in a ref),
     // so editing "valid key" into "wrong key" dispatches the very same
     // SET_HAS_API_KEY(true). It must reset the verdict: keeping the stale
@@ -88,6 +87,9 @@ describe("wizardReducer", () => {
     const cleared = wizardReducer(probed, { type: "SET_HAS_API_KEY", value: false });
     expect(cleared.connectionState).toBe("idle");
     expect(cleared.connection).toBeNull();
+    const changedModel = wizardReducer(probed, { type: "SET_MODEL", value: "vendor-model" });
+    expect(changedModel.connectionState).toBe("idle");
+    expect(changedModel.connection).toBeNull();
   });
 
   it("marks skipped configuration steps and clears model selection", () => {
@@ -152,6 +154,14 @@ describe("wizardReducer", () => {
     expect(state.activationState).toBe("loading");
   });
 
+  it("appends installation commands and output as it arrives", () => {
+    let state = wizardReducer(initialWizardState, { type: "ACTIVATION_LOADING", agentIds: ["codex"] });
+    state = wizardReducer(state, { type: "ACTIVATION_OUTPUT", output: { kind: "command", args: ["npm", "install", "-g", "agent@1.0.0"] } });
+    state = wizardReducer(state, { type: "ACTIVATION_OUTPUT", output: { kind: "output", stream: "stdout", text: "fetching\n" } });
+    state = wizardReducer(state, { type: "ACTIVATION_OUTPUT", output: { kind: "output", stream: "stderr", text: "warning\n" } });
+    expect(state.activationLog).toBe("$ npm install -g agent@1.0.0\nfetching\nwarning\n");
+  });
+
   it("merges retry results and preserves non-secret activation summary", () => {
     let state = wizardReducer(initialWizardState, { type: "ACTIVATION_LOADING", agentIds: ["codex", "opencode"] });
     expect(state.activationResults).toHaveLength(2);
diff --git a/frontend/src/state/wizardReducer.ts b/frontend/src/state/wizardReducer.ts
index 37b8cb9e..2de68712 100644
--- a/frontend/src/state/wizardReducer.ts
+++ b/frontend/src/state/wizardReducer.ts
@@ -1,10 +1,11 @@
-import type { FailureDetail } from "../api/client";
+import type { FailureDetail } from "../backend/errors";
 import type {
   AgentInstallResult,
   ModelsResponse,
   ProbeResponse,
   ProviderId,
   StatusResponse,
+  InstallOutput,
 } from "../types/api";
 
 export type ConfigMode = "provider" | "existing-account" | null;
@@ -18,7 +19,6 @@ export interface WizardState {
   installMissingAgents: boolean;
   configMode: ConfigMode;
   provider: ProviderId;
-  customBaseUrl: string;
   hasApiKey: boolean;
   connection: ProbeResponse | null;
   connectionState: AsyncState;
@@ -44,7 +44,6 @@ export const initialWizardState: WizardState = {
   installMissingAgents: true,
   configMode: null,
   provider: "ppio",
-  customBaseUrl: "",
   hasApiKey: false,
   connection: null,
   connectionState: "idle",
@@ -68,7 +67,6 @@ export type WizardAction =
   | { type: "SET_INSTALL_MISSING"; value: boolean }
   | { type: "SET_CONFIG_MODE"; value: Exclude<ConfigMode, null> }
   | { type: "SET_PROVIDER"; value: ProviderId }
-  | { type: "SET_CUSTOM_BASE"; value: string }
   | { type: "SET_HAS_API_KEY"; value: boolean }
   | { type: "CONNECTION_LOADING" }
   | { type: "CONNECTION_RESULT"; result: ProbeResponse }
@@ -79,6 +77,7 @@ export type WizardAction =
   | { type: "SET_MODEL"; value: string }
   | { type: "REQUEST_ACTIVATION" }
   | { type: "ACTIVATION_LOADING"; agentIds: string[] }
+  | { type: "ACTIVATION_OUTPUT"; output: InstallOutput }
   | {
       type: "ACTIVATION_RESULT";
       results: AgentInstallResult[];
@@ -103,6 +102,16 @@ function mergeResults(
   ];
 }
 
+function formatCommand(args: string[]): string {
+  return args.map((arg) => (/^[A-Za-z0-9_./:@%+=,-]+$/.test(arg) ? arg : JSON.stringify(arg))).join(" ");
+}
+
+function appendActivationOutput(log: string, output: InstallOutput): string {
+  const text = output.kind === "command" ? `$ ${formatCommand(output.args)}\n` : output.text;
+  if (!text) return log;
+  return `${log}${output.kind === "command" && log && !log.endsWith("\n") ? "\n" : ""}${text}`;
+}
+
 export function wizardReducer(state: WizardState, action: WizardAction): WizardState {
   switch (action.type) {
     case "STATUS_LOADING":
@@ -142,15 +151,6 @@ export function wizardReducer(state: WizardState, action: WizardAction): WizardS
         modelsMessage: "",
         model: "",
       };
-    case "SET_CUSTOM_BASE":
-      return {
-        ...state,
-        customBaseUrl: action.value,
-        connection: null,
-        connectionState: "idle",
-        models: [],
-        modelsState: "idle",
-      };
     case "SET_HAS_API_KEY":
       // Any edit of the key invalidates the previous probe verdict. The reducer
       // only sees the non-empty boolean (the secret itself stays in a ref), so
@@ -203,7 +203,7 @@ export function wizardReducer(state: WizardState, action: WizardAction): WizardS
         modelsMessage: action.message,
       };
     case "SET_MODEL":
-      return { ...state, model: action.value };
+      return { ...state, model: action.value, connection: null, connectionState: "idle" };
     case "REQUEST_ACTIVATION":
       return { ...state, activationRequested: true };
     case "ACTIVATION_LOADING":
@@ -215,6 +215,8 @@ export function wizardReducer(state: WizardState, action: WizardAction): WizardS
           ? state.activationResults
           : action.agentIds.map((agent) => ({ agent, status: "skipped", retryable: false })),
       };
+    case "ACTIVATION_OUTPUT":
+      return { ...state, activationLog: appendActivationOutput(state.activationLog, action.output) };
     case "ACTIVATION_RESULT": {
       const activationResults = mergeResults(state.activationResults, action.results, action.replaceAgents);
       return {
diff --git a/frontend/src/styles/app.css b/frontend/src/styles/app.css
index 70c9c75e..385bc2bc 100644
--- a/frontend/src/styles/app.css
+++ b/frontend/src/styles/app.css
@@ -1,56 +1,18 @@
 .desktop-stage {
-  width: 100vw;
-  height: 100vh;
-  padding: 18px;
+  width: 100%;
+  height: 100%;
 }
 
 .app-window {
   width: 100%;
   height: 100%;
-  min-height: 680px;
+  min-height: 0;
   display: grid;
   grid-template-columns: var(--sidebar-width) minmax(0, 1fr);
-  grid-template-rows: var(--titlebar-height) minmax(0, 1fr);
   overflow: hidden;
-  border: 1px solid var(--border-strong);
-  border-radius: var(--radius-window);
   background: var(--window-bg);
-  box-shadow: var(--shadow-window);
-}
-
-.window-chrome {
-  border-bottom: 1px solid var(--border);
-  background: rgba(250, 250, 251, 0.96);
-}
-
-.window-chrome-sidebar {
-  padding: 0 18px;
-  display: flex;
-  align-items: center;
-  gap: 9px;
-  border-right: 1px solid var(--border);
-  background: var(--sidebar-bg);
-}
-
-.window-title {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-size: 13px;
-  font-weight: 600;
 }
 
-.traffic-light {
-  width: 12px;
-  height: 12px;
-  border-radius: 50%;
-  border: 1px solid rgba(0, 0, 0, 0.08);
-}
-
-.traffic-light-red { background: #ff5f57; }
-.traffic-light-yellow { background: #febc2e; }
-.traffic-light-green { background: #28c840; }
-
 .navigation-sidebar {
   min-height: 0;
   padding: 22px 12px 16px;
@@ -75,7 +37,7 @@
   place-items: center;
   border: 1px solid var(--border-strong);
   border-radius: 8px;
-  background: #ffffff;
+  background: var(--window-bg);
 }
 
 .brand-lockup > div {
@@ -88,8 +50,7 @@
   font-size: 16px;
 }
 
-.brand-lockup span:last-child,
-.sidebar-footnote {
+.brand-lockup span:last-child {
   color: var(--text-secondary);
   font-size: 11px;
 }
@@ -99,7 +60,6 @@
   gap: 4px;
 }
 
-.sidebar-primary-action,
 .sidebar-link {
   min-height: 38px;
   padding: 0 10px;
@@ -113,17 +73,6 @@
   transition: background-color 140ms ease, color 140ms ease, transform 100ms ease;
 }
 
-.sidebar-primary-action {
-  margin-bottom: 12px;
-  color: #ffffff;
-  background: var(--blue);
-  font-weight: 600;
-}
-
-.sidebar-primary-action:hover {
-  background: var(--blue-hover);
-}
-
 .sidebar-link:hover,
 .sidebar-link.is-active {
   background: rgba(118, 118, 128, 0.1);
@@ -152,26 +101,38 @@
   text-transform: uppercase;
 }
 
-.sidebar-footnote {
+.language-picker {
+  min-height: 38px;
   margin-top: auto;
-  padding: 12px 10px 0;
-  border-top: 1px solid var(--border);
+  padding: 0 8px;
   display: flex;
   align-items: center;
-  gap: 7px;
+  gap: 8px;
+  color: var(--text-secondary);
+  font-size: 12px;
 }
 
-.privacy-dot {
-  width: 7px;
-  height: 7px;
-  border-radius: 50%;
-  background: var(--green);
+.language-picker span {
+  flex: 1;
+}
+
+.language-picker select {
+  width: 82px;
+  min-width: 0;
+  padding: 5px 6px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-control);
+  background: var(--window-bg);
+  color: var(--text-primary);
+  font: inherit;
 }
 
+.language-select-compact { display: none; }
+
 .app-main {
   min-width: 0;
   min-height: 0;
-  background: #ffffff;
+  background: var(--window-bg);
 }
 
 .page-scaffold {
@@ -183,7 +144,7 @@
 
 .page-header {
   padding: 26px 42px 18px;
-  border-bottom: 1px solid rgba(60, 60, 67, 0.08);
+  border-bottom: 1px solid var(--border-faint);
 }
 
 .page-header > div:first-child {
@@ -223,7 +184,7 @@
   align-items: center;
   justify-content: space-between;
   gap: 20px;
-  background: rgba(250, 250, 251, 0.96);
+  background: var(--footer-bg);
 }
 
 .page-footer-leading,
@@ -288,7 +249,7 @@
   place-items: center;
   border: 1px solid var(--border-strong);
   border-radius: 50%;
-  background: #ffffff;
+  background: var(--window-bg);
   font-size: 13px;
   font-weight: 600;
 }
@@ -345,7 +306,7 @@
   border: 1px solid var(--border);
   border-radius: var(--radius-panel);
   overflow: hidden;
-  background: #ffffff;
+  background: var(--window-bg);
 }
 
 .agent-row {
@@ -394,10 +355,10 @@
   height: 38px;
   display: grid;
   place-items: center;
-  border: 1px solid rgba(60, 60, 67, 0.12);
+  border: 1px solid var(--icon-border);
   border-radius: 7px;
   background: var(--surface-subtle);
-  color: #3a3a3c;
+  color: var(--icon-fg);
 }
 
 .agent-copy,
@@ -455,7 +416,7 @@
 .status-success { color: var(--green); background: var(--green-soft); }
 .status-warning { color: var(--orange); background: var(--orange-soft); }
 .status-danger { color: var(--red); background: var(--red-soft); }
-.status-info { color: #145da0; background: #eff7ff; }
+.status-info { color: var(--info); background: var(--info-soft); }
 .status-neutral { color: var(--text-secondary); background: var(--surface-pressed); }
 
 .agent-selection-body {
@@ -541,7 +502,7 @@
 }
 
 .choice-list {
-  max-width: 760px;
+  width: 100%;
 }
 
 .choice-row {
@@ -553,7 +514,7 @@
   grid-template-columns: 42px minmax(0, 1fr) 24px;
   align-items: center;
   gap: 14px;
-  background: #ffffff;
+  background: var(--window-bg);
   cursor: pointer;
   text-align: left;
 }
@@ -576,29 +537,56 @@
   border-color: var(--blue);
 }
 
-.provider-segment {
-  max-width: 760px;
+.provider-picker {
+  width: 100%;
+  display: grid;
+  gap: 7px;
+}
+
+.provider-picker > label {
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.provider-picker-control {
   display: grid;
-  grid-template-columns: repeat(3, minmax(0, 1fr));
+  grid-template-columns: minmax(0, 1fr) 42px;
+  gap: 8px;
+}
+
+.provider-picker select {
+  width: 100%;
+  min-height: 42px;
+  padding: 0 12px;
   border: 1px solid var(--border-strong);
   border-radius: var(--radius-control);
-  overflow: hidden;
+  color: var(--text-primary);
+  background: var(--window-bg);
 }
 
-.provider-segment button {
-  min-height: 40px;
-  border: 0;
-  border-right: 1px solid var(--border-strong);
-  background: #ffffff;
+.provider-picker select:focus {
+  border-color: var(--blue);
+  box-shadow: 0 0 0 3px var(--blue-soft);
+  outline: none;
+}
+
+.provider-add-button {
+  width: 42px;
+  height: 42px;
+  padding: 0;
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius-control);
+  display: grid;
+  place-items: center;
+  color: var(--text-secondary);
+  background: var(--window-bg);
   cursor: pointer;
 }
 
-.provider-segment button:last-child { border-right: 0; }
-.provider-segment button:hover { background: var(--surface-subtle); }
-.provider-segment button.is-selected { color: var(--blue); background: var(--blue-soft); box-shadow: inset 0 0 0 1px var(--blue); }
+.provider-add-button:hover { color: var(--text-primary); background: var(--surface-subtle); }
 
 .provider-form {
-  max-width: 760px;
+  width: 100%;
   margin-top: 24px;
   display: grid;
   gap: 20px;
@@ -684,7 +672,7 @@
 .inline-status.status-error { color: var(--red); }
 
 .model-picker {
-  max-width: 760px;
+  width: 100%;
   display: grid;
   gap: 16px;
 }
@@ -720,7 +708,7 @@
   align-items: center;
   justify-content: space-between;
   gap: 16px;
-  background: #ffffff;
+  background: var(--window-bg);
   cursor: pointer;
   text-align: left;
 }
@@ -736,7 +724,7 @@
 .empty-row { padding: 18px; color: var(--text-secondary); font-size: 13px; text-align: center; }
 
 .review-columns {
-  max-width: 860px;
+  width: 100%;
   display: grid;
   gap: 22px;
 }
@@ -761,13 +749,13 @@
   font-size: 13px;
 }
 
-.review-row + .review-row { border-top: 1px solid rgba(60, 60, 67, 0.1); }
+.review-row + .review-row { border-top: 1px solid var(--border-faint); }
 .review-row svg { color: var(--green); }
 .review-row > span { color: var(--text-secondary); }
 .review-row strong { min-width: 0; overflow-wrap: anywhere; font-weight: 500; text-align: right; }
 .review-row.is-muted svg { color: var(--text-tertiary); }
 
-.progress-list { max-width: 860px; }
+.progress-list { width: 100%; }
 
 .progress-row {
   min-height: 70px;
@@ -782,7 +770,7 @@
 .progress-icon.is-failed { color: var(--red); background: var(--red-soft); }
 
 .log-disclosure {
-  max-width: 860px;
+  width: 100%;
   margin-top: 18px;
   border-top: 1px solid var(--border);
   border-bottom: 1px solid var(--border);
@@ -818,7 +806,7 @@
 .summary-item strong { overflow: hidden; font-size: 13px; text-overflow: ellipsis; white-space: nowrap; }
 
 .overview-section {
-  max-width: 900px;
+  width: 100%;
   margin-top: 26px;
 }
 
@@ -849,7 +837,7 @@
 .empty-overview span { max-width: 480px; font-size: 13px; line-height: 1.5; }
 
 .next-command-section {
-  max-width: 900px;
+  width: 100%;
   margin-top: 22px;
   position: relative;
 }
@@ -860,7 +848,7 @@
   border: 1px solid var(--border);
   border-radius: var(--radius-control);
   overflow: auto;
-  color: #2c2c2e;
+  color: var(--text-primary);
   background: var(--surface-subtle);
   font: 11px/1.5 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
   white-space: pre-wrap;
@@ -885,7 +873,6 @@
 
 @media (max-width: 1180px) {
   :root { --sidebar-width: 204px; }
-  .desktop-stage { padding: 12px; }
   .page-header { padding: 22px 30px 16px; }
   .page-body { padding: 20px 30px 28px; }
   .page-footer { padding: 0 30px; }
@@ -898,18 +885,17 @@
   .brand-lockup { justify-content: center; padding-inline: 0; }
   .brand-lockup > div,
   .sidebar-link span,
-  .sidebar-primary-action,
   .sidebar-section-label,
-  .sidebar-footnote { display: none; }
+  .language-picker > span,
+  .language-picker > svg { display: none; }
   .sidebar-link { justify-content: center; padding: 0; }
   .sidebar-link.is-active::before { left: -12px; }
-  .window-chrome-sidebar { justify-content: center; padding: 0; gap: 5px; }
-  .traffic-light { width: 9px; height: 9px; }
+  .language-picker { padding: 0; }
+  .language-select-wide { display: none; }
+  .language-select-compact { display: block; width: 48px; padding-inline: 3px; font-size: 10px; }
 }
 
 @media (max-height: 760px) {
-  .desktop-stage { padding: 8px; }
-  .app-window { min-height: 0; }
   .page-header { padding-top: 18px; padding-bottom: 13px; }
   .page-header h1 { font-size: 23px; }
   .setup-stepper { margin-top: 14px; }
@@ -931,15 +917,15 @@
 
 .agent-manage-list {
   display: grid;
-  gap: 8px;
+  gap: 0;
 }
 
-/* One clickable line. Hierarchy comes from spacing and a single divider, not
-   from stacking a border, a fill and a shadow on every row. */
+/* Static environment facts: one scan line per installed Agent. */
 .agent-manage-row {
   width: 100%;
   padding: 11px 13px;
-  display: flex;
+  display: grid;
+  grid-template-columns: 30px minmax(110px, 1.1fr) repeat(3, minmax(90px, 1fr)) minmax(72px, 0.75fr) auto;
   align-items: center;
   gap: 12px;
   border: 0;
@@ -947,17 +933,12 @@
   background: transparent;
   font: inherit;
   text-align: left;
-  cursor: pointer;
-  transition: background 120ms ease;
 }
 
 .agent-manage-row + .agent-manage-row {
   box-shadow: inset 0 1px 0 var(--border);
 }
 
-.agent-manage-row:hover { background: var(--surface-subtle); }
-.agent-manage-row:active { background: var(--surface-pressed); }
-
 .agent-manage-row > .agent-icon {
   flex-shrink: 0;
   width: 30px;
@@ -966,34 +947,35 @@
 }
 
 .agent-manage-row > .agent-manage-identity {
-  flex: 1;
   min-width: 0;
   display: grid;
   gap: 2px;
 }
 
-.agent-manage-version {
-  flex-shrink: 0;
-  color: var(--text-tertiary);
-  font-size: 11px;
+.agent-manage-fact {
+  min-width: 0;
+  display: grid;
+  gap: 2px;
 }
 
-.agent-manage-version.is-behind { color: var(--orange); }
+.agent-manage-fact small {
+  color: var(--text-tertiary);
+  font-size: 10px;
+}
 
-.agent-manage-cta {
-  flex-shrink: 0;
-  display: inline-flex;
-  align-items: center;
-  gap: 2px;
+.agent-manage-fact > span {
+  overflow: hidden;
   color: var(--text-secondary);
-  font-size: 11px;
+  font-size: 12px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
-.agent-manage-row:hover .agent-manage-cta { color: var(--blue); }
+.agent-manage-version.is-behind > span { color: var(--orange); }
 
 .agent-manage-list {
   border-radius: var(--radius-panel);
-  background: #fff;
+  background: var(--window-bg);
 }
 
 /* Detail page */
@@ -1033,7 +1015,12 @@
 .detail-form {
   display: grid;
   gap: 12px;
-  max-width: 560px;
+  width: 100%;
+}
+
+.detail-form .provider-picker {
+  width: 100%;
+  max-width: none;
 }
 
 .detail-protocol {
@@ -1094,12 +1081,73 @@
   padding: 7px 9px;
   overflow-x: auto;
   border-radius: 5px;
-  background: rgba(255, 255, 255, 0.7);
+  background: var(--overlay-panel);
   color: var(--text-primary);
   font-size: 11px;
 }
 
-/* Provider and template cards share one grid so the two pages read as siblings. */
+/* Provider and template management use the same quiet editor rhythm. */
+.provider-toolbar,
+.profile-toolbar {
+  margin-bottom: 12px;
+  display: flex;
+  justify-content: flex-end;
+}
+
+.provider-editor,
+.profile-editor {
+  margin-bottom: 14px;
+  padding: 14px 0;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 14px;
+  border-top: 1px solid var(--border);
+  border-bottom: 1px solid var(--border);
+}
+
+.provider-editor > header,
+.provider-editor > footer,
+.profile-editor > header,
+.profile-editor > footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.provider-editor > footer .button,
+.profile-editor > footer .button { min-width: 0; }
+
+.provider-editor-grid,
+.profile-editor-grid {
+  min-width: 0;
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+}
+
+.provider-editor-grid > *,
+.profile-editor-grid > * { min-width: 0; }
+
+.provider-editor-wide,
+.profile-editor-wide { grid-column: 1 / -1; }
+
+.icon-button {
+  width: 30px;
+  height: 30px;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-control);
+  display: inline-grid;
+  place-items: center;
+  color: var(--text-secondary);
+  background: transparent;
+  cursor: pointer;
+}
+
+.icon-button:hover { color: var(--text-primary); background: var(--surface-pressed); }
+.icon-button.is-danger:hover { color: var(--red); background: var(--red-soft); }
+
 .provider-list,
 .profile-list {
   display: grid;
@@ -1108,6 +1156,7 @@
 
 .provider-card,
 .profile-card {
+  min-width: 0;
   padding: 13px;
   display: grid;
   gap: 9px;
@@ -1126,6 +1175,27 @@
 .provider-card strong,
 .profile-card strong { font-size: 13px; }
 
+.provider-card > * { min-width: 0; }
+
+.provider-title {
+  min-width: 0;
+  display: flex;
+  align-items: baseline;
+  gap: 7px;
+}
+
+.provider-title small {
+  color: var(--text-tertiary);
+  font-size: 10px;
+}
+
+.provider-card-actions {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
 .provider-link {
   display: inline-flex;
   align-items: center;
@@ -1144,6 +1214,7 @@
 }
 
 .provider-endpoints div {
+  min-width: 0;
   display: flex;
   align-items: baseline;
   gap: 9px;
@@ -1157,6 +1228,7 @@
 }
 
 .provider-endpoints dd {
+  min-width: 0;
   margin: 0;
   overflow: hidden;
   color: var(--text-secondary);
@@ -1179,11 +1251,29 @@
 .provider-user-chip {
   padding: 2px 8px;
   border-radius: 999px;
-  background: #fff;
+  background: var(--window-bg);
   color: var(--text-secondary);
   font-size: 11px;
 }
 
+.provider-card footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.provider-key-state {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  color: var(--text-tertiary);
+  font-size: 11px;
+}
+
+.provider-key-state.has-key { color: var(--green); }
+
 .provider-note {
   margin: 14px 0 0;
   color: var(--text-tertiary);
@@ -1201,6 +1291,25 @@
 
 .profile-key.has-key { color: var(--green); }
 
+.profile-title {
+  min-width: 0;
+  display: flex;
+  align-items: baseline;
+  gap: 7px;
+}
+
+.profile-title small {
+  color: var(--text-tertiary);
+  font-size: 10px;
+}
+
+.profile-card-actions {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
 .profile-target {
   margin: 0;
   color: var(--text-secondary);
@@ -1213,6 +1322,29 @@
   font-size: 11px;
 }
 
+.profile-card footer {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.profile-key-hint {
+  margin: 5px 0 0;
+  color: var(--text-tertiary);
+  font-size: 11px;
+}
+
+.profile-agent-picker {
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+
+.profile-agent-picker legend {
+  margin-bottom: 7px;
+  font-size: 13px;
+  font-weight: 600;
+}
+
 /* Every interactive target clears the same minimum height, so a row, a button
    and a disclosure all feel like the same control family. */
 .button,
@@ -1279,3 +1411,104 @@
 
 .agent-manage-row.is-guide .agent-icon { opacity: 0.75; }
 .agent-manage-cta.is-static { color: var(--text-tertiary); }
+
+/* Runtime bootstrap: Node.js and uv rows, plus the selection-page prompt. */
+.runtime-list {
+  display: grid;
+  gap: 0;
+  border-radius: var(--radius-panel);
+  background: var(--window-bg);
+}
+
+.runtime-row {
+  padding: 11px 13px;
+  display: grid;
+  grid-template-columns: minmax(120px, 1.4fr) repeat(2, minmax(90px, 1fr)) minmax(72px, 0.7fr) auto;
+  align-items: center;
+  gap: 12px;
+}
+
+.runtime-row + .runtime-row {
+  box-shadow: inset 0 1px 0 var(--border);
+}
+
+.runtime-identity,
+.runtime-fact {
+  min-width: 0;
+  display: grid;
+  gap: 2px;
+}
+
+.runtime-identity small,
+.runtime-fact small {
+  color: var(--text-tertiary);
+  font-size: 10px;
+}
+
+.runtime-fact > span {
+  overflow: hidden;
+  color: var(--text-secondary);
+  font-size: 12px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.runtime-action-placeholder {
+  display: block;
+  width: 1px;
+}
+
+.runtime-note {
+  margin: 0;
+  color: var(--text-tertiary);
+  font-size: 12px;
+}
+
+.runtime-prompt {
+  align-items: flex-start;
+  gap: 10px;
+}
+
+.runtime-prompt-body {
+  min-width: 0;
+  display: grid;
+  gap: 6px;
+}
+
+.runtime-prompt-body > span {
+  color: var(--text-secondary);
+}
+
+.runtime-prompt-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.runtime-prompt-error {
+  color: var(--red);
+  font-size: 12px;
+}
+
+@media (max-width: 600px) {
+  .provider-editor-grid,
+  .profile-editor-grid { grid-template-columns: minmax(0, 1fr); }
+  .provider-editor-wide,
+  .profile-editor-wide { grid-column: auto; }
+  .provider-card footer { align-items: flex-start; flex-direction: column; }
+
+  .agent-manage-row {
+    grid-template-columns: 30px minmax(0, 1fr) auto;
+    align-items: start;
+  }
+
+  .agent-manage-row > .status-badge { grid-column: 3; grid-row: 1; }
+  .agent-manage-fact { grid-column: 2 / 4; }
+
+  .runtime-row {
+    grid-template-columns: minmax(0, 1fr) auto;
+    align-items: start;
+  }
+
+  .runtime-fact { grid-column: 1 / 3; }
+}
diff --git a/frontend/src/styles/base.css b/frontend/src/styles/base.css
index 569b1997..a26ed9dd 100644
--- a/frontend/src/styles/base.css
+++ b/frontend/src/styles/base.css
@@ -7,6 +7,7 @@ html,
 body,
 #root {
   min-width: 320px;
+  height: 100%;
   min-height: 100%;
   margin: 0;
 }
@@ -20,7 +21,8 @@ body {
 }
 
 button,
-input {
+input,
+select {
   font: inherit;
 }
 
@@ -36,6 +38,7 @@ input[type="checkbox"] {
 
 button:focus-visible,
 input:focus-visible,
+select:focus-visible,
 a:focus-visible {
   outline: 3px solid rgba(0, 122, 255, 0.3);
   outline-offset: 2px;
@@ -80,7 +83,7 @@ button:active:not(:disabled) {
 
 .button-secondary,
 .button-compact {
-  background: #ffffff;
+  background: var(--window-bg);
   border-color: var(--border-strong);
 }
 
@@ -103,7 +106,7 @@ button:active:not(:disabled) {
   border: 1px solid var(--border-strong);
   border-radius: var(--radius-control);
   color: var(--text-primary);
-  background: #ffffff;
+  background: var(--window-bg);
   transition: border-color 140ms ease, box-shadow 140ms ease;
 }
 
@@ -166,8 +169,8 @@ button:active:not(:disabled) {
 }
 
 .notice-info {
-  color: #145da0;
-  background: #eff7ff;
+  color: var(--info);
+  background: var(--info-soft);
   border-color: rgba(0, 122, 255, 0.2);
 }
 
diff --git a/frontend/src/styles/landing.css b/frontend/src/styles/landing.css
deleted file mode 100644
index eba3e2f2..00000000
--- a/frontend/src/styles/landing.css
+++ /dev/null
@@ -1,804 +0,0 @@
-/* Public landing surface: intentionally separate from the compact desktop app shell. */
-.landing-shell {
-  --landing-ink: #0b1117;
-  --landing-ink-soft: #121b24;
-  --landing-ink-panel: #18232d;
-  --landing-paper: #f0ede5;
-  --landing-paper-deep: #e4dfd4;
-  --landing-paper-line: rgba(21, 28, 34, 0.14);
-  --landing-text: #f5f4ef;
-  --landing-muted: #a6b1ba;
-  --landing-muted-dark: #637079;
-  --landing-coral: #ff7555;
-  --landing-coral-deep: #e15d42;
-  --landing-mint: #c8f2d4;
-  --landing-blue: #a6d3ef;
-  --landing-gold: #f3ca74;
-  min-height: 100vh;
-  overflow: hidden;
-  color: var(--landing-text);
-  background: var(--landing-ink);
-}
-
-.landing-shell,
-.landing-shell * {
-  scrollbar-color: rgba(255, 255, 255, 0.24) transparent;
-}
-
-.landing-background-grid {
-  position: fixed;
-  z-index: 0;
-  inset: 0;
-  pointer-events: none;
-  opacity: 0.14;
-  background-image:
-    linear-gradient(rgba(255, 255, 255, 0.045) 1px, transparent 1px),
-    linear-gradient(90deg, rgba(255, 255, 255, 0.045) 1px, transparent 1px);
-  background-size: 72px 72px;
-  mask-image: linear-gradient(to bottom, black, transparent 72%);
-}
-
-.landing-header {
-  position: relative;
-  z-index: 10;
-  border-bottom: 1px solid rgba(232, 240, 245, 0.1);
-  background: rgba(11, 17, 23, 0.78);
-  backdrop-filter: blur(18px);
-}
-
-.landing-nav {
-  width: min(1220px, calc(100% - 64px));
-  min-height: 82px;
-  margin: 0 auto;
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 28px;
-}
-
-.landing-wordmark {
-  display: inline-flex;
-  align-items: center;
-  gap: 12px;
-  color: var(--landing-text);
-  text-decoration: none;
-  font-size: 17px;
-  font-weight: 650;
-  letter-spacing: -0.03em;
-  white-space: nowrap;
-}
-
-.landing-brand-mark {
-  width: 31px;
-  height: 31px;
-  position: relative;
-  display: inline-block;
-  flex: 0 0 auto;
-  border: 1px solid rgba(255, 255, 255, 0.32);
-  border-radius: 9px;
-  background: rgba(255, 255, 255, 0.04);
-  box-shadow: inset 0 0 0 1px rgba(255, 117, 85, 0.12);
-}
-
-.landing-brand-node {
-  width: 6px;
-  height: 6px;
-  position: absolute;
-  z-index: 2;
-  border: 1px solid var(--landing-ink);
-  border-radius: 50%;
-  background: var(--landing-coral);
-  box-shadow: 0 0 0 2px rgba(255, 117, 85, 0.15);
-}
-
-.landing-brand-node-left { top: 7px; left: 7px; }
-.landing-brand-node-right { top: 7px; right: 7px; background: var(--landing-mint); box-shadow: 0 0 0 2px rgba(200, 242, 212, 0.13); }
-.landing-brand-node-bottom { bottom: 6px; left: calc(50% - 3px); background: var(--landing-blue); box-shadow: 0 0 0 2px rgba(166, 211, 239, 0.13); }
-
-.landing-brand-link {
-  position: absolute;
-  z-index: 1;
-  height: 1px;
-  transform-origin: left center;
-  background: rgba(255, 255, 255, 0.5);
-}
-
-.landing-brand-link-one { width: 13px; top: 11px; left: 11px; transform: rotate(0deg); }
-.landing-brand-link-two { width: 12px; top: 14px; left: 10px; transform: rotate(58deg); }
-
-.landing-nav-links,
-.landing-nav-actions {
-  display: flex;
-  align-items: center;
-  gap: 26px;
-}
-
-.landing-nav-links button,
-.landing-nav-login,
-.landing-footer-links button,
-.landing-footer-links a {
-  padding: 0;
-  border: 0;
-  color: var(--landing-muted);
-  background: transparent;
-  text-decoration: none;
-  font-size: 13px;
-  cursor: pointer;
-  transition: color 160ms ease;
-}
-
-.landing-nav-links button:hover,
-.landing-nav-login:hover,
-.landing-footer-links button:hover,
-.landing-footer-links a:hover {
-  color: var(--landing-text);
-}
-
-.landing-nav-cta {
-  min-height: 38px;
-  padding: 0 14px;
-  display: inline-flex;
-  align-items: center;
-  gap: 8px;
-  border: 1px solid rgba(255, 117, 85, 0.62);
-  border-radius: 10px;
-  color: var(--landing-text);
-  background: rgba(255, 117, 85, 0.12);
-  text-decoration: none;
-  font-size: 13px;
-  font-weight: 600;
-  transition: background-color 160ms ease, border-color 160ms ease, transform 160ms ease;
-}
-
-.landing-nav-cta:hover {
-  border-color: var(--landing-coral);
-  background: rgba(255, 117, 85, 0.2);
-  transform: translateY(-1px);
-}
-
-.landing-nav-cta-mobile,
-.landing-mobile-toggle {
-  display: none;
-}
-
-.landing-hero {
-  width: min(1220px, calc(100% - 64px));
-  min-height: 700px;
-  margin: 0 auto;
-  padding: 92px 0 82px;
-  position: relative;
-  z-index: 1;
-  display: grid;
-  grid-template-columns: minmax(0, 0.86fr) minmax(460px, 1.14fr);
-  align-items: center;
-  gap: clamp(56px, 7vw, 116px);
-}
-
-.hero-copy {
-  position: relative;
-  z-index: 2;
-}
-
-.hero-copy h1 {
-  max-width: 690px;
-  margin: 0;
-  color: var(--landing-text);
-  font-size: clamp(56px, 7.25vw, 104px);
-  font-weight: 620;
-  line-height: 0.94;
-  letter-spacing: -0.085em;
-}
-
-.hero-copy h1 span {
-  color: var(--landing-coral);
-}
-
-.hero-lede {
-  max-width: 535px;
-  margin: 30px 0 0;
-  color: var(--landing-muted);
-  font-size: clamp(17px, 1.5vw, 20px);
-  line-height: 1.55;
-  letter-spacing: -0.02em;
-}
-
-.hero-actions {
-  margin-top: 36px;
-  display: flex;
-  align-items: center;
-  flex-wrap: wrap;
-  gap: 14px;
-}
-
-.landing-button {
-  min-height: 52px;
-  padding: 0 19px;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  gap: 10px;
-  border: 1px solid transparent;
-  border-radius: 12px;
-  color: var(--landing-text);
-  text-decoration: none;
-  font-size: 14px;
-  font-weight: 650;
-  cursor: pointer;
-  transition: transform 160ms ease, background-color 160ms ease, border-color 160ms ease;
-}
-
-.landing-button:hover { transform: translateY(-2px); }
-
-.landing-button-primary {
-  color: var(--landing-ink);
-  background: var(--landing-coral);
-  box-shadow: 0 12px 30px rgba(255, 117, 85, 0.2);
-}
-
-.landing-button-primary:hover { background: #ff8668; }
-
-.landing-button-quiet {
-  color: var(--landing-muted);
-  background: transparent;
-  border-color: rgba(232, 240, 245, 0.14);
-}
-
-.landing-button-quiet:hover {
-  color: var(--landing-text);
-  border-color: rgba(232, 240, 245, 0.3);
-  background: rgba(255, 255, 255, 0.04);
-}
-
-.button-arrow {
-  color: var(--landing-coral);
-  font-size: 20px;
-  line-height: 0;
-}
-
-.hero-note {
-  margin-top: 27px;
-  display: flex;
-  align-items: center;
-  flex-wrap: wrap;
-  gap: 10px;
-  color: #87939d;
-  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
-  font-size: 11px;
-  letter-spacing: 0.03em;
-}
-
-.hero-note-dot,
-.hero-live-dot,
-.network-live-dot,
-.demo-ready span,
-.lane-state span {
-  width: 7px;
-  height: 7px;
-  display: inline-block;
-  border-radius: 50%;
-  background: var(--landing-mint);
-  box-shadow: 0 0 0 4px rgba(200, 242, 212, 0.1), 0 0 12px rgba(200, 242, 212, 0.48);
-}
-
-.hero-note-divider {
-  width: 1px;
-  height: 14px;
-  display: inline-block;
-  background: rgba(232, 240, 245, 0.18);
-}
-
-.hero-visual-wrap {
-  position: relative;
-  padding: 15px 18px 16px;
-  border: 1px solid rgba(232, 240, 245, 0.15);
-  border-radius: 25px;
-  background: rgba(18, 27, 36, 0.76);
-  box-shadow: 0 36px 90px rgba(0, 0, 0, 0.34), inset 0 0 0 1px rgba(255, 255, 255, 0.025);
-  transform: rotate(1.2deg);
-}
-
-.hero-visual-wrap::before,
-.hero-visual-wrap::after {
-  position: absolute;
-  z-index: -1;
-  content: "";
-  border: 1px solid rgba(255, 117, 85, 0.16);
-  border-radius: inherit;
-}
-
-.hero-visual-wrap::before { inset: 12px -10px -10px 12px; transform: rotate(-2.2deg); }
-.hero-visual-wrap::after { inset: -9px 14px 14px -12px; border-color: rgba(200, 242, 212, 0.14); transform: rotate(0.9deg); }
-
-.hero-visual-label,
-.hero-visual-footnote {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 16px;
-  color: #7f8c96;
-  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
-  font-size: 10px;
-  letter-spacing: 0.13em;
-  text-transform: uppercase;
-}
-
-.hero-visual-label { padding: 1px 3px 14px; }
-.hero-visual-label > span:last-child { display: inline-flex; align-items: center; gap: 8px; letter-spacing: 0.08em; text-transform: none; }
-.hero-visual-footnote { padding: 12px 3px 0; letter-spacing: 0.04em; text-transform: none; }
-
-.network-map {
-  min-height: 430px;
-  position: relative;
-  overflow: hidden;
-  border: 1px solid rgba(232, 240, 245, 0.1);
-  border-radius: 17px;
-  background:
-    radial-gradient(circle at 50% 48%, rgba(255, 117, 85, 0.13), transparent 27%),
-    radial-gradient(circle at 76% 22%, rgba(200, 242, 212, 0.08), transparent 25%),
-    #0c141c;
-}
-
-.network-map-grid {
-  position: absolute;
-  inset: 0;
-  opacity: 0.5;
-  background-image:
-    linear-gradient(rgba(232, 240, 245, 0.045) 1px, transparent 1px),
-    linear-gradient(90deg, rgba(232, 240, 245, 0.045) 1px, transparent 1px);
-  background-size: 38px 38px;
-  mask-image: radial-gradient(circle at 50% 50%, black 30%, transparent 90%);
-}
-
-.network-map-lines {
-  width: 100%;
-  height: 100%;
-  position: absolute;
-  inset: 0;
-  overflow: visible;
-}
-
-.network-map-lines path {
-  fill: none;
-  stroke: rgba(232, 240, 245, 0.24);
-  stroke-dasharray: 5 8;
-  stroke-width: 1.3;
-  animation: network-line-flow 8s linear infinite;
-}
-
-.network-map-lines circle { fill: var(--landing-coral); opacity: 0.9; }
-
-@keyframes network-line-flow {
-  to { stroke-dashoffset: -104; }
-}
-
-.network-map-radar {
-  position: absolute;
-  top: calc(50% - 92px);
-  left: calc(50% - 92px);
-  width: 184px;
-  height: 184px;
-  border: 1px solid rgba(255, 117, 85, 0.12);
-  border-radius: 50%;
-}
-
-.network-map-radar-two { width: 280px; height: 280px; top: calc(50% - 140px); left: calc(50% - 140px); border-color: rgba(200, 242, 212, 0.08); }
-
-.network-core {
-  width: 142px;
-  height: 142px;
-  position: absolute;
-  top: calc(50% - 71px);
-  left: calc(50% - 71px);
-  z-index: 3;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: 5px;
-  border: 1px solid rgba(255, 117, 85, 0.68);
-  border-radius: 50%;
-  color: var(--landing-text);
-  background: rgba(18, 27, 36, 0.94);
-  box-shadow: 0 0 0 10px rgba(255, 117, 85, 0.06), 0 0 44px rgba(255, 117, 85, 0.22);
-  animation: core-breathe 4.5s ease-in-out infinite;
-}
-
-@keyframes core-breathe {
-  50% { box-shadow: 0 0 0 16px rgba(255, 117, 85, 0.03), 0 0 62px rgba(255, 117, 85, 0.16); }
-}
-
-.network-core-orbit {
-  position: absolute;
-  inset: 10px;
-  border: 1px dashed rgba(200, 242, 212, 0.35);
-  border-radius: 50%;
-  animation: orbit-spin 18s linear infinite;
-}
-
-.network-core-icon {
-  width: 38px;
-  height: 38px;
-  display: grid;
-  place-items: center;
-  border-radius: 12px;
-  color: var(--landing-coral);
-  background: rgba(255, 117, 85, 0.13);
-}
-
-.network-core strong { font-size: 15px; letter-spacing: -0.03em; }
-.network-core span { color: #8a969f; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; letter-spacing: 0.13em; text-transform: uppercase; }
-
-@keyframes orbit-spin { to { transform: rotate(360deg); } }
-
-.network-agent {
-  min-width: 148px;
-  position: absolute;
-  z-index: 4;
-  padding: 12px 11px;
-  display: grid;
-  grid-template-columns: 8px minmax(0, 1fr) auto;
-  align-items: center;
-  gap: 9px;
-  border: 1px solid rgba(232, 240, 245, 0.14);
-  border-radius: 12px;
-  color: var(--landing-text);
-  background: rgba(24, 35, 45, 0.88);
-  box-shadow: 0 10px 24px rgba(0, 0, 0, 0.18);
-  backdrop-filter: blur(10px);
-}
-
-.network-agent-1 { top: 52px; left: 36px; }
-.network-agent-2 { top: 52px; right: 36px; }
-.network-agent-3 { bottom: 58px; left: 38px; }
-.network-agent-4 { right: 36px; bottom: 58px; }
-.network-agent-dot { width: 7px; height: 7px; border-radius: 50%; }
-.network-agent-dot-coral { background: var(--landing-coral); }
-.network-agent-dot-mint { background: var(--landing-mint); }
-.network-agent-dot-blue { background: var(--landing-blue); }
-.network-agent-dot-gold { background: var(--landing-gold); }
-.network-agent strong,
-.network-agent small { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.network-agent strong { font-size: 11px; font-weight: 600; }
-.network-agent small { margin-top: 3px; color: #81909a; font-size: 9px; }
-.network-agent-state { color: #99c7a5; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 8px; }
-
-.network-map-caption {
-  position: absolute;
-  right: 18px;
-  bottom: 14px;
-  left: 18px;
-  z-index: 5;
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  color: #73818b;
-  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
-  font-size: 9px;
-  letter-spacing: 0.04em;
-}
-
-.network-map-caption span:first-child { display: inline-flex; align-items: center; gap: 7px; }
-
-.tool-strip {
-  width: min(1220px, calc(100% - 64px));
-  margin: 0 auto;
-  padding: 22px 0 25px;
-  position: relative;
-  z-index: 1;
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 28px;
-  border-top: 1px solid rgba(232, 240, 245, 0.12);
-  border-bottom: 1px solid rgba(232, 240, 245, 0.12);
-}
-
-.tool-strip-label {
-  color: #7f8b95;
-  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
-  font-size: 10px;
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
-}
-
-.tool-strip-list { display: flex; align-items: center; flex-wrap: wrap; justify-content: flex-end; gap: 12px 25px; }
-.tool-name { display: inline-flex; align-items: center; gap: 7px; color: #c5cdd2; font-size: 13px; letter-spacing: -0.02em; }
-.tool-name svg { color: var(--landing-coral); }
-
-.landing-section { position: relative; z-index: 1; }
-.landing-section-inner { width: min(1220px, calc(100% - 64px)); margin: 0 auto; padding: 124px 0; }
-.landing-section-paper { color: #172027; background: var(--landing-paper); }
-.landing-section-paper + .landing-section-paper { border-top: 1px solid var(--landing-paper-line); }
-.landing-section-ink { background: var(--landing-ink-soft); }
-
-.section-heading-row { display: grid; grid-template-columns: 86px minmax(0, 690px); gap: 25px; align-items: start; }
-.section-heading-row-dark { color: var(--landing-text); }
-.section-index { padding-top: 7px; color: #68757c; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 11px; letter-spacing: 0.12em; }
-.section-heading-row-dark .section-index { color: var(--landing-coral); }
-.section-heading-copy h2 { max-width: 720px; margin: 0; font-size: clamp(38px, 5.2vw, 69px); font-weight: 580; line-height: 0.98; letter-spacing: -0.075em; }
-.section-heading-copy p { max-width: 590px; margin: 23px 0 0; color: #5e6b73; font-size: 17px; line-height: 1.58; letter-spacing: -0.02em; }
-.section-heading-row-dark .section-heading-copy p { color: var(--landing-muted); }
-
-.friction-layout { margin-top: 84px; display: grid; grid-template-columns: minmax(0, 0.78fr) minmax(0, 1.22fr); gap: 70px; align-items: start; }
-.friction-statement { padding: 25px 0 0 48px; position: relative; }
-.friction-quote-mark { position: absolute; top: -9px; left: 0; color: var(--landing-coral); font-family: Georgia, serif; font-size: 86px; line-height: 1; }
-.friction-statement p { max-width: 390px; margin: 0; font-size: clamp(28px, 3vw, 43px); line-height: 1.05; letter-spacing: -0.07em; }
-.friction-statement em { color: #7b888d; font-style: normal; }
-.friction-statement strong { color: var(--landing-coral-deep); font-weight: 620; }
-.friction-rule { width: 100%; max-width: 390px; height: 1px; margin-top: 37px; display: block; background: rgba(21, 28, 34, 0.16); }
-.friction-caption { display: block; max-width: 320px; margin-top: 14px; color: #788389; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 10px; line-height: 1.5; text-transform: uppercase; }
-
-.friction-list { border-top: 1px solid rgba(21, 28, 34, 0.18); }
-.friction-item { min-height: 115px; padding: 21px 0; display: grid; grid-template-columns: 43px minmax(0, 1fr) 28px; gap: 18px; align-items: center; border-bottom: 1px solid rgba(21, 28, 34, 0.18); }
-.friction-icon { width: 38px; height: 38px; display: grid; place-items: center; border-radius: 12px; }
-.friction-icon-coral { color: var(--landing-coral-deep); background: rgba(255, 117, 85, 0.15); }
-.friction-icon-mint { color: #3e7960; background: rgba(90, 173, 128, 0.16); }
-.friction-icon-blue { color: #4d7190; background: rgba(116, 178, 218, 0.18); }
-.friction-item strong { display: block; font-size: 16px; font-weight: 650; letter-spacing: -0.03em; }
-.friction-item div > span { display: block; max-width: 440px; margin-top: 6px; color: #67747a; font-size: 14px; line-height: 1.45; }
-.friction-number { align-self: start; padding-top: 4px; color: #8d989b; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 10px; }
-
-.workflow-section-inner { padding-bottom: 136px; }
-.workflow-layout { margin-top: 75px; display: grid; grid-template-columns: minmax(260px, 0.7fr) minmax(0, 1.3fr); gap: clamp(44px, 7vw, 110px); align-items: center; }
-.workflow-steps { display: grid; gap: 0; }
-.workflow-step { min-height: 112px; padding: 21px 0; display: grid; grid-template-columns: 42px minmax(0, 1fr) 20px; gap: 15px; align-items: start; border-top: 1px solid rgba(232, 240, 245, 0.16); color: #788690; }
-.workflow-step:last-of-type { border-bottom: 1px solid rgba(232, 240, 245, 0.16); }
-.workflow-step-active { color: var(--landing-text); }
-.workflow-step-number { padding-top: 2px; color: var(--landing-coral); font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 11px; }
-.workflow-step strong { display: block; font-size: 17px; font-weight: 630; letter-spacing: -0.035em; }
-.workflow-step p { max-width: 280px; margin: 6px 0 0; color: inherit; font-size: 13px; line-height: 1.45; }
-.workflow-step > svg { margin-top: 2px; color: #60717d; }
-.workflow-step-active > svg { color: var(--landing-mint); }
-.workflow-link { width: fit-content; margin-top: 26px; display: inline-flex; align-items: center; gap: 8px; color: var(--landing-text); text-decoration: none; font-size: 13px; font-weight: 600; }
-.workflow-link svg { color: var(--landing-coral); transition: transform 160ms ease; }
-.workflow-link:hover svg { transform: translate(2px, -2px); }
-
-.demo-window { overflow: hidden; border: 1px solid rgba(232, 240, 245, 0.18); border-radius: 18px; background: #0f1820; box-shadow: 0 28px 70px rgba(0, 0, 0, 0.24); }
-.demo-window-bar { min-height: 43px; padding: 0 15px; display: grid; grid-template-columns: 80px minmax(0, 1fr) 80px; align-items: center; gap: 10px; border-bottom: 1px solid rgba(232, 240, 245, 0.1); color: #75838c; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; letter-spacing: 0.04em; }
-.demo-window-lights { display: flex; gap: 5px; }
-.demo-window-lights span { width: 7px; height: 7px; border-radius: 50%; background: #6e777c; opacity: 0.75; }
-.demo-window-lights span:first-child { background: var(--landing-coral); }
-.demo-window-privacy { display: inline-flex; justify-content: flex-end; align-items: center; gap: 5px; color: #8fbda0; }
-.demo-tabs { padding: 0 17px; display: flex; gap: 20px; border-bottom: 1px solid rgba(232, 240, 245, 0.1); }
-.demo-tab { min-height: 43px; padding: 0; position: relative; border: 0; color: #75838c; background: transparent; font-size: 11px; cursor: pointer; }
-.demo-tab::after { position: absolute; right: 0; bottom: -1px; left: 0; height: 2px; background: transparent; content: ""; }
-.demo-tab:hover { color: #d9e2e5; }
-.demo-tab.is-active { color: var(--landing-text); }
-.demo-tab.is-active::after { background: var(--landing-coral); }
-.demo-panel-content { min-height: 335px; padding: 26px; }
-.demo-status-row,
-.demo-routing-header { display: flex; align-items: start; justify-content: space-between; gap: 18px; }
-.demo-overline { display: block; color: #75838c; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; letter-spacing: 0.12em; }
-.demo-status-row strong,
-.demo-routing-header strong { display: block; margin-top: 6px; color: #eff2ed; font-size: 15px; font-weight: 580; letter-spacing: -0.035em; }
-.demo-ready { display: inline-flex; align-items: center; gap: 8px; color: #9ac4a5; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; white-space: nowrap; }
-.demo-agent-list { margin-top: 26px; border-top: 1px solid rgba(232, 240, 245, 0.12); }
-.demo-agent-row { min-height: 71px; display: grid; grid-template-columns: 31px minmax(0, 1fr) auto 17px; align-items: center; gap: 11px; border-bottom: 1px solid rgba(232, 240, 245, 0.1); }
-.demo-agent-avatar { width: 28px; height: 28px; display: grid; place-items: center; border-radius: 9px; }
-.demo-agent-avatar-coral { color: var(--landing-coral); background: rgba(255, 117, 85, 0.14); }
-.demo-agent-avatar-mint { color: var(--landing-mint); background: rgba(200, 242, 212, 0.1); }
-.demo-agent-avatar-blue { color: var(--landing-blue); background: rgba(166, 211, 239, 0.11); }
-.demo-agent-name strong,
-.demo-agent-name small { display: block; }
-.demo-agent-name strong { color: #e9efed; font-size: 12px; font-weight: 580; }
-.demo-agent-name small { margin-top: 4px; color: #788791; font-size: 10px; }
-.demo-agent-model { color: #aebbc0; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 10px; }
-.demo-check { color: #9ac4a5; }
-.demo-footer-row { min-height: 40px; padding-top: 16px; display: flex; align-items: center; justify-content: space-between; gap: 15px; color: #788791; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; }
-.demo-footer-row span:first-child { display: inline-flex; align-items: center; gap: 7px; }
-.demo-mini-dot { width: 6px; height: 6px; border-radius: 50%; background: var(--landing-mint); }
-.demo-mini-dot-coral { background: var(--landing-coral); }
-
-.demo-routing-header { align-items: center; }
-.demo-route-badge { padding: 6px 8px; border: 1px solid rgba(200, 242, 212, 0.2); color: var(--landing-mint); background: rgba(200, 242, 212, 0.07); font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; }
-.route-track { margin: 61px 0 38px; display: grid; grid-template-columns: minmax(80px, 1fr) minmax(35px, 0.42fr) minmax(80px, 1fr) minmax(35px, 0.42fr) minmax(80px, 1fr); align-items: center; gap: 9px; }
-.route-node { min-height: 86px; padding: 12px 10px; display: grid; justify-items: start; align-content: center; gap: 5px; border: 1px solid rgba(232, 240, 245, 0.17); border-radius: 12px; background: rgba(255, 255, 255, 0.03); }
-.route-node svg { color: var(--landing-coral); }
-.route-node span { color: #eef1ee; font-size: 11px; font-weight: 600; }
-.route-node small { color: #788791; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; }
-.route-node-mint svg { color: var(--landing-mint); }
-.route-node-blue svg { color: var(--landing-blue); }
-.route-line { height: 1px; position: relative; background: rgba(232, 240, 245, 0.22); }
-.route-line i { width: 5px; height: 5px; position: absolute; top: -2px; left: 0; border-radius: 50%; background: var(--landing-coral); animation: route-dot 2.5s ease-in-out infinite; }
-.route-line:nth-of-type(4) i { animation-delay: 0.8s; }
-@keyframes route-dot { 0% { left: 0; opacity: 0; } 18% { opacity: 1; } 78% { opacity: 1; } 100% { left: calc(100% - 5px); opacity: 0; } }
-.route-code { padding: 15px 16px; border: 1px solid rgba(232, 240, 245, 0.1); background: rgba(0, 0, 0, 0.18); color: #cbd8d8; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 10px; line-height: 1.8; }
-.route-code .code-muted { color: #74838b; }
-.route-code b { color: var(--landing-mint); font-weight: 500; }
-
-.demo-add-profile { color: var(--landing-coral); font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; }
-.profile-preview-list { margin-top: 27px; display: grid; gap: 11px; }
-.profile-preview { padding: 16px; border: 1px solid rgba(232, 240, 245, 0.13); background: rgba(255, 255, 255, 0.025); }
-.profile-preview-active { border-color: rgba(255, 117, 85, 0.54); background: rgba(255, 117, 85, 0.07); }
-.profile-preview-top { display: flex; align-items: center; gap: 9px; }
-.profile-symbol { width: 24px; height: 24px; display: grid; place-items: center; border-radius: 7px; font-size: 14px; }
-.profile-symbol-coral { color: var(--landing-coral); background: rgba(255, 117, 85, 0.15); }
-.profile-symbol-mint { color: var(--landing-mint); background: rgba(200, 242, 212, 0.11); }
-.profile-preview-top strong { color: #eef1ee; font-size: 12px; font-weight: 600; }
-.profile-current { margin-left: auto; color: var(--landing-coral); font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 8px; text-transform: uppercase; }
-.profile-preview p { margin: 12px 0 15px 33px; color: #89959d; font-size: 11px; line-height: 1.45; }
-.profile-preview-meta { margin-left: 33px; display: flex; gap: 15px; color: #74838b; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; }
-
-.landing-section-lanes { background: #ece8df; }
-.lanes-layout { margin-top: 82px; display: grid; grid-template-columns: minmax(0, 0.75fr) minmax(0, 1.25fr); gap: clamp(48px, 8vw, 130px); align-items: center; }
-.lanes-copy-head { display: flex; align-items: center; justify-content: space-between; gap: 18px; color: var(--landing-coral-deep); }
-.lanes-kicker { color: #718083; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 10px; letter-spacing: 0.1em; }
-.lanes-copy > p { max-width: 420px; margin: 25px 0 0; color: #536167; font-size: 18px; line-height: 1.55; letter-spacing: -0.03em; }
-.check-list { margin: 30px 0 0; padding: 0; display: grid; gap: 12px; list-style: none; }
-.check-list li { display: flex; align-items: center; gap: 10px; color: #34444b; font-size: 13px; }
-.check-list li svg { color: var(--landing-coral-deep); }
-.text-link { margin-top: 33px; display: inline-flex; align-items: center; gap: 8px; color: #1d2c31; text-decoration: none; font-size: 13px; font-weight: 650; }
-.text-link svg { color: var(--landing-coral-deep); transition: transform 160ms ease; }
-.text-link:hover svg { transform: translate(2px, -2px); }
-
-.lane-stack { overflow: hidden; border: 1px solid rgba(21, 28, 34, 0.2); background: rgba(255, 255, 255, 0.34); }
-.lane-row { min-height: 77px; padding: 0 17px; display: grid; grid-template-columns: 29px 4px minmax(0, 0.85fr) minmax(0, 1.2fr) auto; gap: 13px; align-items: center; border-bottom: 1px solid rgba(21, 28, 34, 0.15); }
-.lane-order { color: #859096; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 10px; }
-.lane-color-bar { width: 4px; height: 31px; border-radius: 3px; background: var(--landing-coral); }
-.lane-row-mint .lane-color-bar { background: #6cb88a; }
-.lane-row-blue .lane-color-bar { background: #78b8dc; }
-.lane-row-gold .lane-color-bar { background: #d9ac52; }
-.lane-agent strong,
-.lane-agent small { display: block; }
-.lane-agent strong { color: #203038; font-size: 13px; font-weight: 650; letter-spacing: -0.03em; }
-.lane-agent small { margin-top: 4px; color: #728087; font-size: 10px; }
-.lane-route { display: inline-flex; align-items: center; gap: 8px; min-width: 0; color: #617178; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; }
-.lane-route span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.lane-route svg { flex: 0 0 auto; color: #9a6d5f; }
-.lane-state { display: inline-flex; align-items: center; gap: 7px; color: #4c7f60; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; }
-.lane-state span { width: 6px; height: 6px; background: #6cb88a; box-shadow: none; }
-.lane-stack-foot { min-height: 46px; padding: 0 17px; display: flex; align-items: center; gap: 20px; color: #738087; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 9px; }
-.lane-stack-foot span + span::before { margin-right: 20px; color: #a3acad; content: "/"; }
-
-.principles-section { position: relative; z-index: 1; overflow: hidden; background: #131d25; }
-.principles-inner { width: min(1220px, calc(100% - 64px)); min-height: 510px; margin: 0 auto; padding: 100px 0; display: grid; grid-template-columns: minmax(300px, 0.9fr) minmax(0, 1.1fr); gap: clamp(48px, 10vw, 160px); align-items: center; }
-.principles-orbit { width: min(410px, 100%); aspect-ratio: 1; position: relative; display: grid; place-items: center; justify-self: center; }
-.principles-orbit::before { position: absolute; width: 55%; height: 55%; border: 1px solid rgba(255, 117, 85, 0.42); border-radius: 50%; content: ""; box-shadow: 0 0 80px rgba(255, 117, 85, 0.12); }
-.principles-orbit-ring { position: absolute; border: 1px solid rgba(200, 242, 212, 0.18); border-radius: 50%; }
-.principles-orbit-ring-one { inset: 10%; transform: rotate(24deg) scaleY(0.64); }
-.principles-orbit-ring-two { inset: 1%; transform: rotate(-23deg) scaleY(0.45); border-color: rgba(166, 211, 239, 0.17); }
-.principles-orbit-core { width: 92px; height: 92px; display: grid; place-items: center; border: 1px solid rgba(255, 117, 85, 0.8); border-radius: 27px; color: var(--landing-coral); background: #17242d; box-shadow: 0 0 0 11px rgba(255, 117, 85, 0.05); }
-.principles-orbit::after { width: 9px; height: 9px; position: absolute; top: 19%; right: 12%; border-radius: 50%; background: var(--landing-mint); box-shadow: 0 0 0 7px rgba(200, 242, 212, 0.08); content: ""; }
-.principles-copy { max-width: 590px; }
-.section-index-accent { color: var(--landing-coral); }
-.principles-copy h2 { margin: 17px 0 0; color: var(--landing-text); font-size: clamp(39px, 5vw, 69px); font-weight: 580; line-height: 0.98; letter-spacing: -0.075em; }
-.principles-copy > p { max-width: 530px; margin: 25px 0 0; color: var(--landing-muted); font-size: 17px; line-height: 1.6; }
-.principles-notes { margin-top: 34px; display: flex; flex-wrap: wrap; gap: 15px 22px; color: #bec8ca; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 10px; }
-.principles-notes span { display: inline-flex; align-items: center; gap: 8px; }
-.principle-dot { width: 6px; height: 6px; display: inline-block; border-radius: 50%; }
-.principle-dot-mint { background: var(--landing-mint); }
-.principle-dot-coral { background: var(--landing-coral); }
-.principle-dot-gold { background: var(--landing-gold); }
-
-.faq-section { position: relative; z-index: 1; color: #172027; background: var(--landing-paper); }
-.faq-inner { display: grid; grid-template-columns: minmax(250px, 0.62fr) minmax(0, 1.38fr); gap: clamp(45px, 10vw, 160px); align-items: start; }
-.faq-intro h2 { margin: 18px 0 0; font-size: clamp(38px, 4.7vw, 61px); font-weight: 580; line-height: 0.98; letter-spacing: -0.075em; }
-.faq-intro p { max-width: 260px; margin: 22px 0 0; color: #69757a; font-size: 15px; line-height: 1.5; }
-.faq-list { border-top: 1px solid rgba(21, 28, 34, 0.18); }
-.faq-item { border-bottom: 1px solid rgba(21, 28, 34, 0.18); }
-.faq-item > button { width: 100%; min-height: 76px; padding: 0; display: flex; align-items: center; justify-content: space-between; gap: 25px; border: 0; color: #1d2a30; background: transparent; font-size: 16px; font-weight: 620; text-align: left; cursor: pointer; }
-.faq-item > button svg { flex: 0 0 auto; color: var(--landing-coral-deep); transition: transform 180ms ease; }
-.faq-item.is-open > button svg { transform: rotate(180deg); }
-.faq-answer { max-width: 650px; padding: 0 48px 22px 0; }
-.faq-answer p { margin: 0; color: #68757a; font-size: 14px; line-height: 1.6; }
-
-.final-cta { min-height: 490px; position: relative; z-index: 1; overflow: hidden; display: grid; place-items: center; text-align: center; background: var(--landing-coral); }
-.final-cta-grid { position: absolute; inset: 0; opacity: 0.18; background-image: linear-gradient(rgba(11, 17, 23, 0.18) 1px, transparent 1px), linear-gradient(90deg, rgba(11, 17, 23, 0.18) 1px, transparent 1px); background-size: 72px 72px; }
-.final-cta-inner { max-width: 700px; padding: 80px 24px; position: relative; z-index: 1; }
-.final-cta-mark { display: flex; justify-content: center; }
-.final-cta-mark .landing-brand-mark { border-color: rgba(11, 17, 23, 0.48); background: rgba(255, 255, 255, 0.1); }
-.final-cta-mark .landing-brand-node { border-color: var(--landing-coral); }
-.final-cta-mark .landing-brand-link { background: rgba(11, 17, 23, 0.6); }
-.final-cta-inner h2 { margin: 24px 0 0; color: var(--landing-ink); font-size: clamp(47px, 6vw, 82px); font-weight: 620; line-height: 0.92; letter-spacing: -0.085em; }
-.final-cta-inner p { max-width: 500px; margin: 24px auto 0; color: rgba(11, 17, 23, 0.7); font-size: 17px; line-height: 1.5; }
-.landing-button-final { margin-top: 31px; color: var(--landing-text); background: var(--landing-ink); box-shadow: 0 14px 32px rgba(11, 17, 23, 0.18); }
-.landing-button-final:hover { background: #1b2730; }
-.final-cta-note { display: block; margin-top: 16px; color: rgba(11, 17, 23, 0.56); font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 10px; }
-
-.landing-footer { position: relative; z-index: 1; color: var(--landing-muted); background: var(--landing-ink); }
-.landing-footer-inner { width: min(1220px, calc(100% - 64px)); min-height: 88px; margin: 0 auto; display: flex; align-items: center; justify-content: space-between; gap: 25px; }
-.landing-footer-copy { color: #75828b; font-size: 12px; }
-.landing-footer-links { display: flex; align-items: center; gap: 18px; }
-.landing-footer-links span { color: #65727b; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 10px; }
-
-@media (max-width: 980px) {
-  .landing-hero { grid-template-columns: 1fr; gap: 62px; padding-top: 72px; }
-  .hero-copy { max-width: 760px; }
-  .hero-visual-wrap { max-width: 760px; margin-left: auto; }
-  .friction-layout,
-  .workflow-layout,
-  .lanes-layout { grid-template-columns: 1fr; gap: 54px; }
-  .friction-statement { padding-left: 45px; }
-  .workflow-layout { align-items: start; }
-  .workflow-steps { max-width: 650px; }
-  .demo-window { width: 100%; }
-  .principles-inner { grid-template-columns: 0.75fr 1.25fr; gap: 45px; }
-}
-
-@media (max-width: 760px) {
-  .landing-nav,
-  .landing-hero,
-  .tool-strip,
-  .landing-section-inner,
-  .principles-inner,
-  .landing-footer-inner { width: min(100% - 36px, 560px); }
-  .landing-nav { min-height: 70px; }
-  .landing-nav-actions { gap: 14px; }
-  .landing-nav-login,
-  .landing-nav-actions > .landing-nav-cta { display: none; }
-  .landing-mobile-toggle { width: 37px; height: 37px; display: grid; place-items: center; border: 1px solid rgba(232, 240, 245, 0.18); border-radius: 10px; color: var(--landing-text); background: transparent; cursor: pointer; }
-  .landing-nav-links { position: absolute; top: 70px; right: 18px; left: 18px; padding: 12px; display: none; align-items: stretch; flex-direction: column; gap: 0; border: 1px solid rgba(232, 240, 245, 0.15); border-radius: 14px; background: rgba(18, 27, 36, 0.97); box-shadow: 0 22px 50px rgba(0, 0, 0, 0.32); }
-  .landing-nav-links.is-open { display: flex; }
-  .landing-nav-links button { min-height: 46px; padding: 0 12px; text-align: left; }
-  .landing-nav-cta-mobile { display: inline-flex; justify-content: center; margin-top: 8px; }
-  .landing-hero { min-height: auto; padding: 68px 0 74px; }
-  .hero-copy h1 { font-size: clamp(53px, 16vw, 86px); }
-  .hero-lede { margin-top: 24px; font-size: 16px; }
-  .hero-actions { margin-top: 28px; align-items: stretch; flex-direction: column; }
-  .landing-button { width: 100%; }
-  .hero-note { line-height: 1.7; }
-  .hero-visual-wrap { padding: 12px; transform: none; }
-  .network-map { min-height: 390px; }
-  .network-agent { min-width: 125px; padding: 10px 9px; grid-template-columns: 7px minmax(0, 1fr); }
-  .network-agent-state { display: none; }
-  .network-agent-1 { top: 35px; left: 16px; }
-  .network-agent-2 { top: 35px; right: 16px; }
-  .network-agent-3 { bottom: 55px; left: 16px; }
-  .network-agent-4 { right: 16px; bottom: 55px; }
-  .network-core { width: 126px; height: 126px; top: calc(50% - 63px); left: calc(50% - 63px); }
-  .network-map-radar { top: calc(50% - 80px); left: calc(50% - 80px); width: 160px; height: 160px; }
-  .network-map-radar-two { top: calc(50% - 125px); left: calc(50% - 125px); width: 250px; height: 250px; }
-  .tool-strip { align-items: flex-start; flex-direction: column; gap: 17px; }
-  .tool-strip-list { justify-content: flex-start; gap: 13px 18px; }
-  .landing-section-inner { padding: 84px 0; }
-  .section-heading-row { grid-template-columns: 42px minmax(0, 1fr); gap: 15px; }
-  .section-heading-copy h2 { font-size: clamp(39px, 11vw, 58px); }
-  .section-heading-copy p { margin-top: 18px; font-size: 15px; }
-  .friction-layout,
-  .workflow-layout,
-  .lanes-layout { margin-top: 55px; }
-  .friction-statement { padding-left: 38px; }
-  .friction-statement p { font-size: 36px; }
-  .friction-item { min-height: 124px; grid-template-columns: 38px minmax(0, 1fr); gap: 13px; }
-  .friction-number { display: none; }
-  .demo-window-bar { grid-template-columns: 70px minmax(0, 1fr) auto; }
-  .demo-window-privacy { font-size: 0; }
-  .demo-window-privacy svg { margin-left: auto; }
-  .demo-panel-content { min-height: 330px; padding: 20px 17px; }
-  .demo-agent-row { grid-template-columns: 29px minmax(0, 1fr) 17px; gap: 9px; }
-  .demo-agent-model { display: none; }
-  .route-track { grid-template-columns: 1fr; gap: 8px; margin: 34px 0 25px; }
-  .route-node { min-height: 62px; grid-template-columns: 20px minmax(0, 1fr) auto; align-items: center; }
-  .route-node small { grid-column: 3; grid-row: 1; }
-  .route-line { width: 1px; height: 17px; margin-left: 19px; }
-  .route-line i { top: 0; left: -2px; animation: route-dot-vertical 2.5s ease-in-out infinite; }
-  @keyframes route-dot-vertical { 0% { top: 0; opacity: 0; } 18% { opacity: 1; } 78% { opacity: 1; } 100% { top: 12px; opacity: 0; } }
-  .profile-preview p,
-  .profile-preview-meta { margin-left: 0; }
-  .lane-row { min-height: 92px; padding: 12px 13px; grid-template-columns: 22px 4px minmax(0, 1fr) auto; gap: 10px; }
-  .lane-route { grid-column: 3 / 5; grid-row: 2; padding-top: 2px; }
-  .lane-state { grid-column: 4; grid-row: 1; }
-  .lane-stack-foot { gap: 12px; }
-  .lane-stack-foot span + span::before { margin-right: 12px; }
-  .principles-inner { min-height: auto; padding: 84px 0; grid-template-columns: 1fr; gap: 55px; }
-  .principles-orbit { width: min(310px, 85vw); order: 2; }
-  .principles-copy h2 { font-size: clamp(41px, 11vw, 60px); }
-  .principles-copy > p { font-size: 15px; }
-  .faq-inner { grid-template-columns: 1fr; gap: 55px; }
-  .faq-intro p { max-width: 340px; }
-  .faq-item > button { min-height: 70px; font-size: 15px; }
-  .faq-answer { padding-right: 24px; }
-  .final-cta { min-height: 470px; }
-  .final-cta-inner h2 { font-size: clamp(49px, 14vw, 72px); }
-  .final-cta-inner p { font-size: 15px; }
-  .landing-footer-inner { min-height: auto; padding: 25px 0; align-items: flex-start; flex-direction: column; gap: 17px; }
-  .landing-footer-copy { max-width: 280px; }
-  .landing-footer-links { flex-wrap: wrap; gap: 12px 17px; }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .network-map-lines path,
-  .network-core,
-  .network-core-orbit,
-  .route-line i { animation: none; }
-}
diff --git a/frontend/src/styles/tokens.css b/frontend/src/styles/tokens.css
index 0063e0e6..f2adf268 100644
--- a/frontend/src/styles/tokens.css
+++ b/frontend/src/styles/tokens.css
@@ -1,5 +1,5 @@
 :root {
-  color-scheme: light;
+  color-scheme: light dark;
   font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", Arial, sans-serif;
   font-synthesis: none;
   text-rendering: optimizeLegibility;
@@ -13,6 +13,11 @@
   --text-tertiary: #8e8e93;
   --border: rgba(60, 60, 67, 0.18);
   --border-strong: rgba(60, 60, 67, 0.28);
+  --border-faint: rgba(60, 60, 67, 0.08);
+  --icon-border: rgba(60, 60, 67, 0.12);
+  --icon-fg: #3a3a3c;
+  --footer-bg: rgba(250, 250, 251, 0.96);
+  --overlay-panel: rgba(255, 255, 255, 0.7);
   --blue: #007aff;
   --blue-hover: #006ee6;
   --blue-soft: rgba(0, 122, 255, 0.08);
@@ -22,11 +27,44 @@
   --orange-soft: #fff3e7;
   --red: #d70015;
   --red-soft: #fff0f1;
+  --info: #145da0;
+  --info-soft: #eff7ff;
   --shadow-window: 0 22px 55px rgba(42, 42, 46, 0.16), 0 2px 8px rgba(42, 42, 46, 0.08);
   --radius-control: 6px;
   --radius-panel: 8px;
   --radius-window: 12px;
   --sidebar-width: 232px;
-  --titlebar-height: 52px;
   --footer-height: 68px;
 }
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --page-bg: #151517;
+    --window-bg: #1e1e20;
+    --sidebar-bg: rgba(24, 24, 26, 0.94);
+    --surface-subtle: #2c2c2e;
+    --surface-pressed: #3a3a3c;
+    --text-primary: #f5f5f7;
+    --text-secondary: #98989d;
+    --text-tertiary: #6e6e73;
+    --border: rgba(255, 255, 255, 0.14);
+    --border-strong: rgba(255, 255, 255, 0.22);
+    --border-faint: rgba(255, 255, 255, 0.08);
+    --icon-border: rgba(255, 255, 255, 0.12);
+    --icon-fg: #d1d1d6;
+    --footer-bg: rgba(28, 28, 30, 0.96);
+    --overlay-panel: rgba(0, 0, 0, 0.25);
+    --blue: #0a84ff;
+    --blue-hover: #409cff;
+    --blue-soft: rgba(10, 132, 255, 0.16);
+    --green: #30d158;
+    --green-soft: #1e3726;
+    --orange: #ff9f0a;
+    --orange-soft: #3a2c12;
+    --red: #ff453a;
+    --red-soft: #3a1213;
+    --info: #7cc4ff;
+    --info-soft: #12283a;
+    --shadow-window: 0 22px 55px rgba(0, 0, 0, 0.55), 0 2px 8px rgba(0, 0, 0, 0.35);
+  }
+}
diff --git a/frontend/src/test/setup.ts b/frontend/src/test/setup.ts
index a18945a9..d8dd1bd3 100644
--- a/frontend/src/test/setup.ts
+++ b/frontend/src/test/setup.ts
@@ -1,7 +1,71 @@
 import "@testing-library/jest-dom/vitest";
 import { cleanup } from "@testing-library/react";
-import { afterEach } from "vitest";
+import { afterEach, beforeEach } from "vitest";
 
 // vitest runs without injected globals, so RTL's built-in auto-cleanup (which
 // registers on a global afterEach) never engages; do it explicitly.
 afterEach(() => cleanup());
+
+/**
+ * Node exposes its own experimental `localStorage`, which shadows the jsdom
+ * implementation and reads as `undefined` unless the process was started with
+ * `--localstorage-file`. Tests assert that an API key never reaches browser
+ * storage, and against `undefined` those assertions cannot fail for the right
+ * reason -- `JSON.stringify(undefined)` is itself `undefined`, so a matcher
+ * either errors or vacuously passes. Installing a real in-memory Storage makes
+ * the assertions meaningful: a leak now has somewhere to be found.
+ */
+function memoryStorage(): Storage {
+	let entries = new Map<string, string>();
+	const storage: Storage = {
+		get length() {
+			return entries.size;
+		},
+		clear() {
+			entries = new Map();
+		},
+		getItem(key: string) {
+			return entries.has(key) ? (entries.get(key) as string) : null;
+		},
+		key(index: number) {
+			return [...entries.keys()][index] ?? null;
+		},
+		removeItem(key: string) {
+			entries.delete(key);
+		},
+		setItem(key: string, value: string) {
+			entries.set(String(key), String(value));
+		},
+	};
+	// JSON.stringify on a real Storage serializes its own enumerable keys. The
+	// object above keeps entries in a Map, so expose them the same way.
+	return new Proxy(storage, {
+		get(target, property, receiver) {
+			if (typeof property === "string" && !(property in target)) {
+				return entries.get(property);
+			}
+			return Reflect.get(target, property, receiver);
+		},
+		ownKeys() {
+			return [...entries.keys()];
+		},
+		getOwnPropertyDescriptor(_target, property) {
+			if (typeof property === "string" && entries.has(property)) {
+				return { value: entries.get(property), enumerable: true, configurable: true, writable: true };
+			}
+			return undefined;
+		},
+	});
+}
+
+function installStorage(name: "localStorage" | "sessionStorage"): void {
+	const storage = memoryStorage();
+	for (const target of [window, globalThis]) {
+		Object.defineProperty(target, name, { value: storage, configurable: true, writable: true });
+	}
+}
+
+beforeEach(() => {
+	installStorage("localStorage");
+	installStorage("sessionStorage");
+});
diff --git a/frontend/src/types/api.ts b/frontend/src/types/api.ts
index 1ae6cd0a..d5566e28 100644
--- a/frontend/src/types/api.ts
+++ b/frontend/src/types/api.ts
@@ -1,192 +1,109 @@
+import type * as AppModels from "../../bindings/github.com/MaimoryLab/OneAgent/internal/app/models.js";
+import type * as BindingModels from "../../bindings/github.com/MaimoryLab/OneAgent/internal/binding/models.js";
+import type * as CatalogModels from "../../bindings/github.com/MaimoryLab/OneAgent/internal/catalog/models.js";
+import type * as PlatformModels from "../../bindings/github.com/MaimoryLab/OneAgent/internal/platform/models.js";
+import type * as ProviderModels from "../../bindings/github.com/MaimoryLab/OneAgent/internal/provider/models.js";
+
 export type PlatformId = "macos" | "windows" | "linux";
 export type AgentGroupId = "auto" | "gateway" | "platform" | "ide";
-export type ProviderId = "ppio" | "novita" | "custom";
+export type ProviderId = string;
+export type ProtocolId = "openai" | "anthropic" | "responses";
 
-export interface AgentCatalogItem {
-  id: string;
-  name: string;
+export const PROTOCOL_LABELS: Record<ProtocolId, string> = {
+  openai: "OpenAI Chat Completions",
+  anthropic: "Anthropic Messages",
+  responses: "OpenAI Responses",
+};
+
+// The generated models are the backend DTO source of truth. These aliases only
+// narrow catalog-controlled strings and non-null successful responses for UI use.
+export type AgentCatalogItem = Omit<CatalogModels.CatalogItem, "group" | "configMode" | "protocol" | "platforms"> & {
   group: AgentGroupId;
   configMode: "auto" | "guide";
-  guideOnly: boolean;
-  lockedVersion: string | null;
-  /** Inference protocol this Agent speaks; null for guide-only Agents. */
   protocol: ProtocolId | null;
   platforms: PlatformId[];
-  platformNote: string;
-  /** Display prominence; lower sorts first. Independent of configMode. */
-  rank: number;
-}
-
-export interface AgentStatus {
-  installed: boolean;
-  configured: boolean;
-  guideOnly: boolean;
-  config: string;
-  version: string | null;
-  lockedVersion: string | null;
-  canInstall: boolean;
-  /** What this Agent is pointed at. Null until it has been configured once. */
-  provider: string | null;
-  model: string | null;
-  baseUrl: string | null;
-  updatedAt: string | null;
-  /**
-   * What the Agent's own config file says, read from disk.
-   *
-   * Alongside the fields above rather than instead of them: those come from
-   * OneAgent's own record and only exist for configurations it wrote, so a
-   * disagreement between the two means the config changed outside OneAgent —
-   * which is itself worth showing. Null for a guide-only Agent, or when there is
-   * no config file yet. Carries no credential, by design.
-   */
-  detected: DetectedConfig | null;
-}
-
-export interface DetectedConfig {
-  baseUrl: string;
-  model: string;
-  /** Whether the file carries the markers OneAgent's own writes leave behind. */
-  managedByOneAgent: boolean;
-  /** Why the file could not be read, when it could not be. */
-  unreadable: string | null;
-}
-
-export interface ActivateAgentResponse {
-  ok: boolean;
-  agent: string;
-  config: string;
-  provider: string;
-  model: string;
-  /** How to make the rewritten config take effect; Agents read it at startup. */
-  restart: string;
-  next: string;
-}
-
-export interface EnvironmentProfile {
-  schema_version: number;
-  id?: string;
-  label?: string;
-  provider: string;
-  base_url: string | null;
-  model: string | null;
-  config_mode: "provider" | "existing-account";
-  agent_ids: string[];
-  activated_at: string;
-  created_at?: string;
-}
-
-export interface ProfileSummary {
-  id: string;
-  label: string;
-  provider: string;
-  baseUrl: string | null;
-  model: string | null;
-  agentIds: string[];
-  activatedAt: string | null;
-  hasKey: boolean;
-}
+};
 
-export interface StatusResponse {
-  apiVersion: number;
-  platform: { os: PlatformId; arch: string; shell: string };
-  capabilities: {
+export type AgentStatus = AppModels.AgentStatus;
+export type DetectedConfig = AppModels.DetectedConfig;
+export type RuntimeStatus = AppModels.RuntimeStatus;
+export type InstallRuntimeResult = Omit<AppModels.InstallRuntimeResult, "runtimes"> & { runtimes: RuntimeStatus[] };
+export type ActivateAgentResponse = BindingModels.ActivateResponse;
+export type OpenRegistrationResponse = BindingModels.OpenRegistrationResponse;
+export type ProviderEntry = ProviderModels.Entry;
+export type SaveProviderInput = BindingModels.SaveProviderRequest;
+export type ProfileSummary = Omit<AppModels.ProfileSummary, "agentIds"> & { agentIds: string[] };
+
+export type StatusResponse = Omit<
+  AppModels.StatusResponse,
+  "platform" | "capabilities" | "agents" | "catalog" | "groups" | "providers" | "mirrors" | "paths" | "backups" | "profiles" | "runtimes"
+> & {
+  platform: Omit<PlatformModels.Info, "os"> & { os: PlatformId };
+  capabilities: Omit<AppModels.Capabilities, "canInstall" | "missingRuntime" | "supportedAgentIds"> & {
     canInstall: Record<string, boolean>;
+    /** Agent id -> runtime id that must be installed before the Agent can be. */
+    missingRuntime: Record<string, string>;
     supportedAgentIds: string[];
   };
+  runtimes: RuntimeStatus[];
   agents: Record<string, AgentStatus>;
   catalog: AgentCatalogItem[];
-  groups: Array<{ id: AgentGroupId; name: string }>;
-  providers: Record<string, { name: string; home: string; base_url: string; anthropic_base_url?: string }>;
-  /**
-   * Package registries the user may install from. The official one is the
-   * default; a mirror is only ever an explicit choice, and `upstream` is carried
-   * so the UI can show where a package ultimately comes from.
-   */
-  mirrors: Array<{ id: string; name: string; registry: string; upstream: string; note: string }>;
+  groups: Array<Omit<CatalogModels.Group, "id"> & { id: AgentGroupId }>;
+  providers: Record<string, CatalogModels.Provider>;
+  mirrors: CatalogModels.Mirror[];
   paths: Record<string, string>;
   backups: Record<string, boolean>;
-  environment: EnvironmentProfile | null;
-  environmentError: string | null;
   profiles: ProfileSummary[];
-  activeProfile: string | null;
-}
-
-export interface ApiErrorShape {
-  ok: false;
-  error: string;
-  message: string;
-  status: number;
-  error_code: string;
-  retryable: boolean;
-}
-
-export type ProtocolId = "openai" | "anthropic" | "responses";
-
-export const PROTOCOL_LABELS: Record<ProtocolId, string> = {
-  openai: "OpenAI Chat Completions",
-  anthropic: "Anthropic Messages",
-  responses: "OpenAI Responses",
 };
 
-export interface ProbeResponse {
-  ok: boolean;
-  reachable: boolean;
-  status: number;
-  message: string;
-  error_code: string | null;
-  retryable: boolean;
-  /** Which protocol this result describes. Absent on pre-protocol responses. */
+export type ProbeResponse = Omit<BindingModels.ProbeResponse, "protocol" | "protocols"> & {
   protocol?: ProtocolId;
-  /** One entry per protocol the selected Agents speak. */
   protocols?: Partial<Record<ProtocolId, ProbeResponse>>;
-}
+};
 
-export interface ModelsResponse extends ProbeResponse {
+export type ModelsResponse = Omit<BindingModels.ModelsResponse, "models" | "protocol" | "protocols"> & ProbeResponse & {
   models: string[];
-}
+};
 
 export type AgentResultStatus = "configured" | "guide-only" | "installed" | "skipped" | "failed";
 
-export interface AgentInstallResult {
-  agent: string;
+export type AgentInstallResult = Omit<
+  BindingModels.AgentInstallResult,
+  "status" | "config" | "installed" | "version" | "lockedVersion" | "registry" | "code" | "error_code" | "message"
+> & {
   status: AgentResultStatus;
+  config?: string;
   installed?: boolean;
   version?: string | null;
   lockedVersion?: string | null;
-  config?: string;
+  registry?: string;
   code?: number;
   error_code?: string;
   message?: string;
-  retryable: boolean;
-}
+};
 
-export interface InstallResponse {
-  ok: boolean;
-  code: number;
+export type InstallResponse = Omit<BindingModels.InstallResponse, "results" | "probe" | "probes"> & {
   results: AgentInstallResult[];
-  log: string;
-  next: string;
   probe: ProbeResponse | null;
-}
+  probes?: Partial<Record<ProtocolId, ProbeResponse>>;
+};
 
-export interface ProviderInput {
-  provider: ProviderId;
-  api_base_url?: string;
-  api_key: string;
-}
+export type InstallOutput =
+  | { kind: "command"; args: string[] }
+  | { kind: "output"; stream: "stdout" | "stderr"; text: string };
 
-export interface InstallRequest extends ProviderInput {
+export type InstallRequest = Pick<
+  BindingModels.InstallRequest,
+  "api_key" | "model" | "configure" | "install_agent" | "skip_test"
+> & {
   agents: string[];
-  model: string;
-  /** Claude Code only: a cheaper model for fast/background work. Empty follows
-   *  `model`; the backend ignores it for every other adapter. */
+  provider: ProviderId;
+  api_base_url?: string;
   small_fast_model?: string;
-  configure: boolean;
-  install_agent: boolean;
-  skip_test: boolean;
   locked_version?: boolean;
   latest?: boolean;
   profile_agents?: string[];
-  /** Mirror id or https:// URL. Omit for the official registry. */
   registry?: string;
-}
+  profile_id?: string;
+  timeout?: number;
+};
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index 0525b691..6ecb026e 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -1,8 +1,12 @@
 import react from "@vitejs/plugin-react";
 import { defineConfig } from "vitest/config";
 
-export default defineConfig({
-  base: "./",
+export default defineConfig(({ command }) => ({
+  // Relative base is required for the packaged app (assets served from an
+  // embedded FS with no fixed root), but Vite's dev server does not support
+  // a relative base and will emit broken asset URLs (blank screen under
+  // `wails3 dev`). Only apply it to the production build.
+  base: command === "build" ? "./" : "/",
   plugins: [react()],
   build: {
     outDir: "dist",
@@ -21,7 +25,13 @@ export default defineConfig({
     coverage: {
       provider: "v8",
       reporter: ["text", "json-summary"],
-      include: ["src/api/**/*.ts", "src/state/**/*.ts", "src/state/**/*.tsx"],
+      // The maintained binding adapter and UI state stay covered; browser E2E
+      // moves to the Wails server-build phase.
+      include: [
+        "src/backend/**/*.ts",
+        "src/state/**/*.ts",
+        "src/state/**/*.tsx",
+      ],
       thresholds: {
         branches: 85,
         functions: 85,
@@ -30,4 +40,4 @@ export default defineConfig({
       },
     },
   },
-});
+}));
diff --git a/go.mod b/go.mod
new file mode 100644
index 00000000..dc1fac2f
--- /dev/null
+++ b/go.mod
@@ -0,0 +1,19 @@
+module github.com/MaimoryLab/OneAgent
+
+go 1.26.5
+
+require (
+	github.com/pelletier/go-toml/v2 v2.4.3
+	github.com/wailsapp/wails/v3 v3.0.0-beta.2
+)
+
+require (
+	github.com/adrg/xdg v0.5.3 // indirect
+	github.com/coder/websocket v1.8.15 // indirect
+	github.com/go-ole/go-ole v1.3.0 // indirect
+	github.com/godbus/dbus/v5 v5.2.2 // indirect
+	github.com/jchv/go-winloader v0.0.0-20250406163304-c1995be93bd1 // indirect
+	github.com/mattn/go-colorable v0.1.15 // indirect
+	github.com/mattn/go-isatty v0.0.24 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+)
diff --git a/go.sum b/go.sum
new file mode 100644
index 00000000..d9c0f7e4
--- /dev/null
+++ b/go.sum
@@ -0,0 +1,36 @@
+github.com/adrg/xdg v0.5.3 h1:xRnxJXne7+oWDatRhR1JLnvuccuIeCoBu2rtuLqQB78=
+github.com/adrg/xdg v0.5.3/go.mod h1:nlTsY+NNiCBGCK2tpm09vRqfVzrc2fLmXGpBLF0zlTQ=
+github.com/coder/websocket v1.8.15 h1:6B2JPeOGlpff2Uz6vOEH1Vzpi0iUz20A+lPVhPHtNUA=
+github.com/coder/websocket v1.8.15/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e h1:Lf/gRkoycfOBPa42vU2bbgPurFong6zXeFtPoxholzU=
+github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e/go.mod h1:uNVvRXArCGbZ508SxYYTC5v1JWoz2voff5pm25jU1Ok=
+github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE=
+github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78=
+github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
+github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/jchv/go-winloader v0.0.0-20250406163304-c1995be93bd1 h1:njuLRcjAuMKr7kI3D85AXWkw6/+v9PwtV6M6o11sWHQ=
+github.com/jchv/go-winloader v0.0.0-20250406163304-c1995be93bd1/go.mod h1:alcuEEnZsY1WQsagKhZDsoPCRoOijYqhZvPwLG0kzVs=
+github.com/matryer/is v1.4.1 h1:55ehd8zaGABKLXQUe2awZ99BD/PTc2ls+KV/dXphgEQ=
+github.com/matryer/is v1.4.1/go.mod h1:8I/i5uYgLzgsgEloJE1U6xx5HkBQpAZvepWuujKwMRU=
+github.com/mattn/go-colorable v0.1.15 h1:+u9SLTRGnXv73cEsnsmoZBom+dMU88B2M0aDcWy0/jY=
+github.com/mattn/go-colorable v0.1.15/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
+github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
+github.com/pelletier/go-toml/v2 v2.4.3 h1:GTRvJQutkOSftxIFD5xw9aepkYNuPWmVJpffdDPYVpY=
+github.com/pelletier/go-toml/v2 v2.4.3/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/wailsapp/wails/v3 v3.0.0-beta.2 h1:hCq2v5iwvhuwZfrowBQA6MHonD4jn+1H9mfk1TGoI/M=
+github.com/wailsapp/wails/v3 v3.0.0-beta.2/go.mod h1:BzATbK71VFikMMMCo434wAi0QcaI03P+xeaWgDvQvjw=
+golang.org/x/sys v0.0.0-20200810151505-1b9f1253b3ed/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/internal/app/agent.go b/internal/app/agent.go
new file mode 100644
index 00000000..74f48b10
--- /dev/null
+++ b/internal/app/agent.go
@@ -0,0 +1,242 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	configWriter "github.com/MaimoryLab/OneAgent/internal/config"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	profileStore "github.com/MaimoryLab/OneAgent/internal/profile"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+)
+
+// ActivateAgentOptions is the transport-independent input for pointing one
+// managed Agent at a Provider. APIKey is deliberately kept inside the use
+// case and never appears in ActivateAgentResult.
+type ActivateAgentOptions struct {
+	AgentID        string
+	Provider       string
+	APIBaseURL     string
+	APIKey         string
+	Model          string
+	ProfileID      string
+	SmallFastModel string
+}
+
+// ActivateAgentResult contains only the public outcome needed by the UI and
+// CLI. The binding itself is persisted separately and is not repeated here.
+type ActivateAgentResult struct {
+	AgentID  string                    `json:"agent"`
+	Config   string                    `json:"config"`
+	Provider string                    `json:"provider"`
+	Model    string                    `json:"model"`
+	Restart  string                    `json:"restart"`
+	Next     string                    `json:"next"`
+	Binding  profileStore.AgentBinding `json:"binding"`
+}
+
+var managedAgentIDPattern = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
+
+// ActivateAgent points one Agent at a Provider while leaving all other Agent
+// files untouched. The write lock covers model resolution and every write so
+// concurrent Wails calls cannot interleave backups or publish stale bindings.
+func (u *UseCases) ActivateAgent(ctx context.Context, options ActivateAgentOptions) (ActivateAgentResult, error) {
+	if u == nil {
+		return ActivateAgentResult{}, oneerrors.New(oneerrors.InternalError, "Agent service is not configured", oneerrors.WithStatus(501))
+	}
+	if err := contextError(ctx, "Agent activation request was cancelled"); err != nil {
+		return ActivateAgentResult{}, err
+	}
+
+	u.writeMu.Lock()
+	defer u.writeMu.Unlock()
+
+	manifest, err := catalog.LoadEmbedded()
+	if err != nil {
+		return ActivateAgentResult{}, err
+	}
+	agentID := options.AgentID
+	if !managedAgentIDPattern.MatchString(agentID) {
+		return ActivateAgentResult{}, oneerrors.New(oneerrors.InvalidRequest, fmt.Sprintf("Invalid Agent ID: %s", agentID))
+	}
+	agent, ok := manifest.Agents[agentID]
+	if !ok {
+		return ActivateAgentResult{}, oneerrors.New(oneerrors.InvalidRequest, "Unknown Agent: "+agentID)
+	}
+	if !contains(agent.Platforms, u.status.Platform.OS) {
+		return ActivateAgentResult{}, oneerrors.New(
+			oneerrors.PrerequisiteMissing,
+			fmt.Sprintf("%s is not supported on %s", agent.Name, u.status.Platform.OS),
+		)
+	}
+	if agent.ConfigMode != "auto" {
+		return ActivateAgentResult{}, oneerrors.New(oneerrors.InvalidRequest, fmt.Sprintf("%s is guide-only and has no managed configuration", agentID))
+	}
+
+	providerID := strings.TrimSpace(options.Provider)
+	if providerID == "" {
+		providerID = "ppio"
+	}
+	target, err := u.providers.Resolve(providerID, options.APIBaseURL)
+	if err != nil {
+		return ActivateAgentResult{}, err
+	}
+	apiKey := options.APIKey
+	profileID := strings.TrimSpace(options.ProfileID)
+	if apiKey == "" && profileID != "" {
+		apiKey, err = u.profiles.ReadSecret(ctx, profileID)
+		if err != nil {
+			return ActivateAgentResult{}, err
+		}
+	}
+	if apiKey == "" {
+		apiKey = target.APIKey
+	}
+	if apiKey == "" {
+		return ActivateAgentResult{}, oneerrors.New(oneerrors.InvalidRequest, "API key is required")
+	}
+	if err := u.providers.SaveKey(ctx, providerID, apiKey); err != nil {
+		return ActivateAgentResult{}, err
+	}
+
+	model, err := u.resolveProviderModel(ctx, target, apiKey, options.Model)
+	if err != nil {
+		return ActivateAgentResult{}, err
+	}
+	if model == "" {
+		return ActivateAgentResult{}, oneerrors.New(oneerrors.InvalidRequest, "model is required")
+	}
+
+	baseURL := target.BaseURL
+	protocol := provider.ProtocolForAdapter(agent.ConfigAdapter)
+	configBaseURL := target.BaseFor(protocol)
+	providerName := target.Name
+	configPath := configPath(u.status.Home, u.status.Platform.OS, agent)
+	if configPath == "" {
+		return ActivateAgentResult{}, oneerrors.New(oneerrors.InvalidRequest, "Managed Agent has no configuration path")
+	}
+
+	filesystem := u.filesystem
+	if needsAgentEnv(agent) {
+		envPath := agentEnvPath(u.status.Home, u.status.Platform.OS, agentID)
+		if err := configWriter.WriteAgentEnv(
+			ctx,
+			filesystem,
+			envPath,
+			u.status.Platform.OS,
+			agentID,
+			apiKey,
+			baseURL,
+			model,
+			options.SmallFastModel,
+			agent.EnvVars,
+		); err != nil {
+			return ActivateAgentResult{}, err
+		}
+	}
+
+	writer := configWriter.NewWriter(u.status.Home, u.status.Platform.OS, filesystem)
+	if err := writeManagedAgentConfig(ctx, writer, agentID, agent, configPath, providerName, configBaseURL, apiKey, model, options.SmallFastModel); err != nil {
+		return ActivateAgentResult{}, err
+	}
+	binding, err := u.profiles.WriteAgentBinding(ctx, agentID, profileStore.BindingWriteRequest{
+		Provider:   providerID,
+		BaseURL:    configBaseURL,
+		Model:      model,
+		ProfileRef: profileID,
+	})
+	if err != nil {
+		return ActivateAgentResult{}, err
+	}
+
+	return ActivateAgentResult{
+		AgentID:  agentID,
+		Config:   configPath,
+		Provider: providerID,
+		Model:    model,
+		Restart:  restartHint(agentID, agent),
+		Next:     nextStep(u.status.Platform.OS, agentID, agent, model),
+		Binding:  binding,
+	}, nil
+}
+
+func contextError(ctx context.Context, message string) error {
+	if ctx == nil {
+		return nil
+	}
+	if err := ctx.Err(); err != nil {
+		return oneerrors.New(oneerrors.Timeout, message, oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+	}
+	return nil
+}
+
+func needsAgentEnv(agent catalog.Agent) bool {
+	return agent.CredentialDelivery == "oneagent_env" || agent.CredentialDelivery == "native_env"
+}
+
+func agentEnvPath(home, osID, agentID string) string {
+	suffix := ".env"
+	if osID == "windows" {
+		suffix = ".env.ps1"
+	}
+	return filepath.Join(home, ".oneagent", "agents", agentID+suffix)
+}
+
+func writeManagedAgentConfig(ctx context.Context, writer configWriter.Writer, agentID string, agent catalog.Agent, path, providerName, baseURL, apiKey, model, smallFastModel string) error {
+	switch agent.ConfigAdapter {
+	case "codex":
+		return writer.WriteCodex(ctx, path, providerName, baseURL, model)
+	case "claude-code":
+		return writer.WriteClaude(ctx, path, baseURL, apiKey, model, smallFastModel)
+	case "opencode":
+		return writer.WriteOpenAICompatible(ctx, path, "https://opencode.ai/config.json", providerName, baseURL, model, agentID)
+	case "kilo-cli":
+		return writer.WriteOpenAICompatible(ctx, path, "https://app.kilo.ai/config.json", providerName, baseURL, model, agentID)
+	case "aider":
+		return writer.WriteAider(ctx, path, baseURL, apiKey)
+	default:
+		return oneerrors.New(oneerrors.InvalidRequest, fmt.Sprintf("Unsupported auto-config Agent: %s", agentID))
+	}
+}
+
+func restartHint(agentID string, agent catalog.Agent) string {
+	if agent.Command == "" {
+		return "Restart " + agentID
+	}
+	if agentID == "aider" {
+		return "Restart " + agent.Command + " in a shell that sources ~/.oneagent/aider.env"
+	}
+	if needsAgentEnv(agent) {
+		return fmt.Sprintf("Quit any running %s process, then start it again in a shell that sources ~/.oneagent/agents/%s.env", agent.Command, agentID)
+	}
+	return fmt.Sprintf("Quit any running %s process, then start it again", agent.Command)
+}
+
+func nextStep(osID, agentID string, agent catalog.Agent, model string) string {
+	if agent.ConfigMode != "auto" || agent.Command == "" {
+		return ""
+	}
+	joiner := "&&"
+	if osID == "windows" {
+		joiner = ";"
+	}
+	if agentID == "aider" {
+		source := "source ~/.oneagent/aider.env"
+		if osID == "windows" {
+			source = `. "$HOME\\.oneagent\\aider.ps1"`
+		}
+		return fmt.Sprintf("%s %s %s --model openai/%s", source, joiner, agent.Command, model)
+	}
+	if needsAgentEnv(agent) {
+		source := fmt.Sprintf("source ~/.oneagent/agents/%s.env", agentID)
+		if osID == "windows" {
+			source = fmt.Sprintf(`. "$HOME\\.oneagent\\agents\\%s.env.ps1"`, agentID)
+		}
+		return fmt.Sprintf("%s %s %s", source, joiner, agent.Command)
+	}
+	return agent.Command
+}
diff --git a/internal/app/agent_test.go b/internal/app/agent_test.go
new file mode 100644
index 00000000..14def79a
--- /dev/null
+++ b/internal/app/agent_test.go
@@ -0,0 +1,211 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+)
+
+func activationCore(t *testing.T, home string, client *provider.Client, osID string) *UseCases {
+	t.Helper()
+	return NewUseCasesWithProviderClient(StatusOptions{
+		Home:     home,
+		Platform: platform.For(osID, "amd64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	}, client)
+}
+
+func TestActivateAgentWritesPerAgentStateAndKeepsSecretsOutOfResult(t *testing.T) {
+	home := t.TempDir()
+	core := activationCore(t, home, provider.NewClient(nil), "linux")
+	result, err := core.ActivateAgent(context.Background(), ActivateAgentOptions{
+		AgentID:  "codex",
+		Provider: "ppio",
+		APIKey:   "codex-secret",
+		Model:    "model-a",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.AgentID != "codex" || result.Provider != "ppio" || result.Model != "model-a" {
+		t.Fatalf("activation result = %#v", result)
+	}
+	if !strings.Contains(result.Restart, "codex") || !strings.Contains(result.Next, "source ~/.oneagent/agents/codex.env") {
+		t.Fatalf("activation hints = %#v", result)
+	}
+	if strings.Contains(result.Restart+result.Next, "codex-secret") {
+		t.Fatal("activation hints leaked the API key")
+	}
+
+	envPath := filepath.Join(home, ".oneagent", "agents", "codex.env")
+	envData, err := os.ReadFile(envPath)
+	if err != nil || !strings.Contains(string(envData), "codex-secret") || !strings.Contains(string(envData), "ONEAGENT_API_KEY_CODEX") {
+		t.Fatalf("Agent env = %q, err=%v", envData, err)
+	}
+	configData, err := os.ReadFile(result.Config)
+	if err != nil || strings.Contains(string(configData), "codex-secret") || !strings.Contains(string(configData), `model_provider = "oneagent"`) {
+		t.Fatalf("Codex config = %q, err=%v", configData, err)
+	}
+	binding, err := core.profiles.ReadAgentBinding("codex")
+	if err != nil || binding == nil || binding.Provider != "ppio" || binding.Model != "model-a" {
+		t.Fatalf("binding = %#v, err=%v", binding, err)
+	}
+	providerEntry, err := core.GetProvider(context.Background(), "ppio")
+	if err != nil || providerEntry.APIKey != "codex-secret" {
+		t.Fatalf("saved Provider key = %#v, err=%v", providerEntry, err)
+	}
+	wire, err := json.Marshal(result)
+	if err != nil || strings.Contains(string(wire), "codex-secret") || strings.Contains(string(wire), "api_key") {
+		t.Fatalf("activation result leaked secret material: %s (%v)", wire, err)
+	}
+
+	if _, err := core.ActivateAgent(context.Background(), ActivateAgentOptions{
+		AgentID:  "opencode",
+		Provider: "novita",
+		APIKey:   "other-secret",
+		Model:    "model-b",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	opencodeEnv, err := os.ReadFile(filepath.Join(home, ".oneagent", "agents", "opencode.env"))
+	if err != nil || !strings.Contains(string(opencodeEnv), "other-secret") || strings.Contains(string(opencodeEnv), "codex-secret") {
+		t.Fatalf("isolated OpenCode env = %q, err=%v", opencodeEnv, err)
+	}
+	codexEnv, _ := os.ReadFile(envPath)
+	if strings.Contains(string(codexEnv), "other-secret") {
+		t.Fatal("activating OpenCode changed Codex credentials")
+	}
+}
+
+func TestActivateAgentReusesProfileKeyAndDiscoversModel(t *testing.T) {
+	home := t.TempDir()
+	client := provider.NewClient(appProviderDoer(func(request *http.Request) (*http.Response, error) {
+		if request.Method != http.MethodGet || request.URL.Path != "/openai/v1/models" {
+			t.Fatalf("unexpected model discovery request: %s %s", request.Method, request.URL.Path)
+		}
+		return appProviderResponse(http.StatusOK, `{"data":[{"id":"embed-v1"},{"id":"chat-model"}]}`), nil
+	}))
+	core := activationCore(t, home, client, "linux")
+	if _, err := core.SaveProfile(context.Background(), SaveProfileOptions{
+		ID:       "team",
+		Provider: "ppio",
+		Model:    "saved-model",
+		APIKey:   "stored-secret",
+		AgentIDs: []string{"opencode"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	result, err := core.ActivateAgent(context.Background(), ActivateAgentOptions{
+		AgentID:   "opencode",
+		Provider:  "ppio",
+		ProfileID: "team",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Model != "chat-model" {
+		t.Fatalf("resolved model = %q", result.Model)
+	}
+	binding, err := core.profiles.ReadAgentBinding("opencode")
+	if err != nil || binding == nil || binding.ProfileRef != "team" {
+		t.Fatalf("profile-linked binding = %#v, err=%v", binding, err)
+	}
+	configData, _ := os.ReadFile(result.Config)
+	if strings.Contains(string(configData), "stored-secret") {
+		t.Fatal("OpenCode config leaked the profile key")
+	}
+}
+
+func TestActivateAgentDispatchesAllManagedAdapters(t *testing.T) {
+	home := t.TempDir()
+	core := activationCore(t, home, provider.NewClient(nil), "linux")
+	for _, agentID := range []string{"codex", "claude-code", "opencode", "kilo-cli", "aider"} {
+		t.Run(agentID, func(t *testing.T) {
+			result, err := core.ActivateAgent(context.Background(), ActivateAgentOptions{
+				AgentID:  agentID,
+				Provider: "ppio",
+				APIKey:   "adapter-secret-" + agentID,
+				Model:    "model-a",
+			})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if _, err := os.Stat(result.Config); err != nil {
+				t.Fatalf("config %s was not written: %v", result.Config, err)
+			}
+			if binding, err := core.profiles.ReadAgentBinding(agentID); err != nil || binding == nil {
+				t.Fatalf("binding = %#v, err=%v", binding, err)
+			}
+		})
+	}
+	claude, err := os.ReadFile(filepath.Join(home, ".claude", "settings.json"))
+	if err != nil || !strings.Contains(string(claude), "adapter-secret-claude-code") {
+		t.Fatalf("Claude native config = %q, err=%v", claude, err)
+	}
+	aider, err := os.ReadFile(filepath.Join(home, ".oneagent", "aider.env"))
+	if err != nil || !strings.Contains(string(aider), "adapter-secret-aider") {
+		t.Fatalf("Aider config = %q, err=%v", aider, err)
+	}
+}
+
+func TestActivateAgentRejectsInvalidInputsAndDoesNotPublishFailedBinding(t *testing.T) {
+	home := t.TempDir()
+	core := activationCore(t, home, provider.NewClient(nil), "linux")
+	for _, options := range []ActivateAgentOptions{
+		{AgentID: "cursor", Provider: "ppio", APIKey: "key", Model: "model"},
+		{AgentID: "no-such-agent", Provider: "ppio", APIKey: "key", Model: "model"},
+		{AgentID: "../escape", Provider: "ppio", APIKey: "key", Model: "model"},
+		{AgentID: "codex", Provider: "ppio", Model: "model"},
+	} {
+		if _, err := core.ActivateAgent(context.Background(), options); err == nil {
+			t.Errorf("invalid activation %#v unexpectedly succeeded", options)
+		}
+	}
+
+	path := filepath.Join(home, ".config", "opencode", "opencode.jsonc")
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	original := "{\n  // keep this comment\n  \"theme\": \"dark\"\n}\n"
+	if err := os.WriteFile(path, []byte(original), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := core.ActivateAgent(context.Background(), ActivateAgentOptions{
+		AgentID:  "opencode",
+		Provider: "ppio",
+		APIKey:   "key",
+		Model:    "model",
+	}); err == nil || !strings.Contains(err.Error(), "JSONC comments") {
+		t.Fatalf("JSONC activation error = %v", err)
+	}
+	if got, _ := os.ReadFile(path); string(got) != original {
+		t.Fatalf("failed activation modified JSONC: %q", got)
+	}
+	if binding, err := core.profiles.ReadAgentBinding("opencode"); err != nil || binding != nil {
+		t.Fatalf("failed activation published binding = %#v, err=%v", binding, err)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if _, err := core.ActivateAgent(ctx, ActivateAgentOptions{AgentID: "codex", Provider: "ppio", APIKey: "key", Model: "model"}); err == nil {
+		t.Fatal("cancelled activation unexpectedly succeeded")
+	}
+	if _, err := core.profiles.ReadAgentBinding("codex"); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestActivateAgentRejectsUnsupportedPlatform(t *testing.T) {
+	core := NewUseCases(StatusOptions{Home: t.TempDir(), Platform: platform.Info{OS: "plan9", Arch: "x64", Shell: "sh"}})
+	_, err := core.ActivateAgent(context.Background(), ActivateAgentOptions{AgentID: "codex", Provider: "ppio", APIKey: "key", Model: "model"})
+	if err == nil || !strings.Contains(err.Error(), "not supported") {
+		t.Fatalf("unsupported platform error = %v", err)
+	}
+}
diff --git a/internal/app/install.go b/internal/app/install.go
new file mode 100644
index 00000000..c053f79f
--- /dev/null
+++ b/internal/app/install.go
@@ -0,0 +1,628 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+	"slices"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	configWriter "github.com/MaimoryLab/OneAgent/internal/config"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/install"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+	profileStore "github.com/MaimoryLab/OneAgent/internal/profile"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+)
+
+// InstallAgentsOptions is one installation request. The use case deliberately
+// keeps the request independent of Wails or CLI transport types so both entry
+// points exercise the same validation and write ordering.
+type InstallAgentsOptions struct {
+	Agents         []string
+	ProfileAgents  []string
+	Provider       string
+	APIBaseURL     string
+	APIKey         string
+	Model          string
+	SmallFastModel string
+	Configure      bool
+	InstallAgent   bool
+	CheckAgentOnly bool
+	SkipTest       bool
+	LockedVersion  bool
+	Latest         bool
+	Timeout        time.Duration
+	Registry       string
+	Output         process.OutputListener
+	// ProfileID is optional. A configured install without one keeps the current
+	// profile ID, or uses "default" on the first run.
+	ProfileID string
+}
+
+// InstallOptions is retained as a convenient compatibility name for callers
+// that used the earlier Go orchestration prototype.
+type InstallOptions = InstallAgentsOptions
+
+// AgentInstallResult is the public per-Agent outcome. It contains no key or
+// process output; the latter is reduced to the redacted aggregate Log field.
+type AgentInstallResult struct {
+	Agent         string `json:"agent"`
+	Status        string `json:"status"`
+	Config        string `json:"config,omitempty"`
+	Installed     bool   `json:"installed,omitempty"`
+	Version       string `json:"version,omitempty"`
+	LockedVersion string `json:"lockedVersion,omitempty"`
+	Registry      string `json:"registry,omitempty"`
+	Code          int    `json:"code,omitempty"`
+	ErrorCode     string `json:"error_code,omitempty"`
+	Message       string `json:"message,omitempty"`
+	Retryable     bool   `json:"retryable"`
+	// checkOnly distinguishes the check path's skipped result from a normal
+	// configure=false result. The public contract includes config only for the
+	// latter, not for check-agent-only results.
+	checkOnly bool
+}
+
+// AgentResult is the short compatibility name used by the first Go port.
+type AgentResult = AgentInstallResult
+
+// InstallAgentsResult is the final aggregate outcome of one request.
+type InstallAgentsResult struct {
+	OK      bool                            `json:"ok"`
+	Code    int                             `json:"code"`
+	Results []AgentInstallResult            `json:"results"`
+	Log     string                          `json:"log"`
+	Next    string                          `json:"next"`
+	Probe   *provider.ProbeResult           `json:"probe"`
+	Probes  map[string]provider.ProbeResult `json:"probes"`
+}
+
+// InstallResult is retained for callers of the earlier orchestration API.
+type InstallResult = InstallAgentsResult
+
+// InstallAgents validates, installs and configures the requested Agents. A
+// failure for one Agent is recorded and the remaining Agents are still tried;
+// request-shape and manifest errors are returned before any write occurs.
+func (u *UseCases) InstallAgents(ctx context.Context, options InstallAgentsOptions) (InstallAgentsResult, error) {
+	if u == nil {
+		return InstallAgentsResult{}, oneerrors.New(oneerrors.InternalError, "Agent service is not configured", oneerrors.WithStatus(501))
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if err := contextError(ctx, "Agent installation request was cancelled"); err != nil {
+		return InstallAgentsResult{}, err
+	}
+
+	// Installation writes env/config/profile/binding files. Keep the whole
+	// operation under the same coordinator as Activate and SaveProfile so two
+	// Wails calls cannot interleave backups or publish a stale profile pointer.
+	u.writeMu.Lock()
+	defer u.writeMu.Unlock()
+
+	manifest, err := catalog.LoadEmbedded()
+	if err != nil {
+		return InstallAgentsResult{}, err
+	}
+	options, err = u.validateInstall(ctx, manifest, options)
+	if err != nil {
+		return InstallAgentsResult{}, err
+	}
+
+	autoAgents := make([]string, 0, len(options.Agents))
+	for _, id := range options.Agents {
+		agent := manifest.Agents[id]
+		if agent.ConfigMode == "auto" {
+			autoAgents = append(autoAgents, id)
+		}
+	}
+
+	baseURL, providerName, err := u.prepareInstallCredentials(ctx, options, manifest, autoAgents)
+	if err != nil {
+		return InstallAgentsResult{}, err
+	}
+	probes, err := u.probeInstallProtocols(ctx, options, manifest, autoAgents)
+	if err != nil {
+		return InstallAgentsResult{}, err
+	}
+
+	run := installRun{
+		core:         u,
+		manifest:     manifest,
+		options:      options,
+		providerName: providerName,
+		probes:       probes,
+		output:       options.Output,
+	}
+	for _, agentID := range options.Agents {
+		run.step(ctx, agentID)
+	}
+	return run.finish(ctx, baseURL), nil
+}
+
+// validateInstall rejects an unusable request before credentials or config are
+// written. Model resolution happens here so every later step uses one value.
+func (u *UseCases) validateInstall(ctx context.Context, manifest catalog.Manifest, options InstallAgentsOptions) (InstallAgentsOptions, error) {
+	if options.LockedVersion && options.Latest {
+		return options, oneerrors.New(oneerrors.InvalidRequest, "locked_version and latest cannot be enabled together")
+	}
+	if options.Timeout <= 0 {
+		return options, oneerrors.New(oneerrors.InvalidRequest, "timeout must be greater than zero")
+	}
+	if len(options.Agents) == 0 {
+		return options, oneerrors.New(oneerrors.InvalidRequest, "At least one Agent is required")
+	}
+	if strings.TrimSpace(options.Provider) == "" {
+		options.Provider = "ppio"
+	}
+	target, err := u.providers.Resolve(options.Provider, options.APIBaseURL)
+	if err != nil {
+		return options, err
+	}
+	profileID := strings.TrimSpace(options.ProfileID)
+	if profileID != "" {
+		if err := profileStore.ValidateID(profileID); err != nil {
+			return options, err
+		}
+		options.ProfileID = profileID
+	}
+	if options.APIKey == "" {
+		if profileID != "" {
+			options.APIKey, err = u.profiles.ReadSecret(ctx, profileID)
+			if err != nil {
+				return options, err
+			}
+		}
+		if options.APIKey == "" {
+			options.APIKey = target.APIKey
+		}
+	}
+	if options.Configure && options.ProfileID == "" {
+		options.ProfileID = u.profiles.LoadActive().ID
+		if options.ProfileID == "" {
+			options.ProfileID = "default"
+		}
+	}
+	profileAgents := append([]string(nil), options.ProfileAgents...)
+	if len(profileAgents) == 0 {
+		profileAgents = append([]string(nil), options.Agents...)
+	}
+	options.ProfileAgents = profileAgents
+	listed := make(map[string]bool, len(profileAgents))
+	for _, id := range profileAgents {
+		listed[id] = true
+	}
+	for _, id := range options.Agents {
+		if !listed[id] {
+			return options, oneerrors.New(oneerrors.InvalidRequest, "profile_agents must include every requested Agent")
+		}
+	}
+	for _, id := range append(append([]string(nil), options.Agents...), profileAgents...) {
+		if _, present := manifest.Agents[id]; !present {
+			return options, oneerrors.New(oneerrors.InvalidRequest, "Unknown Agent: "+id)
+		}
+	}
+	// Validate the registry even when all commands are already installed. This
+	// prevents an invalid setting from being silently accepted on a no-op run.
+	if _, err := install.ResolveRegistry(options.Registry); err != nil {
+		return options, err
+	}
+	if strings.TrimSpace(options.Model) == "" {
+		if options.SkipTest {
+			options.Model = target.FallbackModel
+		} else {
+			if u.provider == nil {
+				return options, oneerrors.New(oneerrors.InternalError, "Model discovery is not configured", oneerrors.WithStatus(501))
+			}
+			model, err := u.resolveProviderModel(ctx, target, options.APIKey, "")
+			if err != nil {
+				return options, err
+			}
+			options.Model = model
+		}
+	}
+	return options, nil
+}
+
+func (u *UseCases) prepareInstallCredentials(ctx context.Context, options InstallAgentsOptions, manifest catalog.Manifest, autoAgents []string) (baseURL, providerName string, err error) {
+	if !options.Configure || len(autoAgents) == 0 || options.CheckAgentOnly {
+		return "", "", nil
+	}
+	if options.APIKey == "" {
+		return "", "", oneerrors.New(oneerrors.InvalidRequest, "API key is required")
+	}
+	if err := u.providers.SaveKey(ctx, options.Provider, options.APIKey); err != nil {
+		return "", "", err
+	}
+	target, err := u.providers.Resolve(options.Provider, options.APIBaseURL)
+	if err != nil {
+		return "", "", err
+	}
+	baseURL = target.BaseURL
+	providerName = target.Name
+	wroteAny := false
+	for _, agentID := range autoAgents {
+		agent := manifest.Agents[agentID]
+		if !needsAgentEnv(agent) {
+			continue
+		}
+		path := agentEnvPath(u.status.Home, u.status.Platform.OS, agentID)
+		if err := configWriter.WriteAgentEnv(ctx, u.filesystem, path, u.status.Platform.OS, agentID, options.APIKey, baseURL, options.Model, options.SmallFastModel, agent.EnvVars); err != nil {
+			return "", "", err
+		}
+		wroteAny = true
+	}
+	if wroteAny {
+		// Keep the legacy shared file while configurations written by older
+		// versions may still reference ONEAGENT_API_KEY.
+		path := filepath.Join(u.status.Home, ".oneagent", envFilename(u.status.Platform.OS))
+		if err := configWriter.WriteSharedEnv(ctx, u.filesystem, path, u.status.Platform.OS, options.APIKey, baseURL); err != nil {
+			return "", "", err
+		}
+	}
+	return baseURL, providerName, nil
+}
+
+func (u *UseCases) probeInstallProtocols(ctx context.Context, options InstallAgentsOptions, manifest catalog.Manifest, autoAgents []string) (map[string]provider.ProbeResult, error) {
+	probes := make(map[string]provider.ProbeResult)
+	if !options.Configure || len(autoAgents) == 0 || options.SkipTest || options.CheckAgentOnly {
+		return probes, nil
+	}
+	target, err := u.providers.Resolve(options.Provider, options.APIBaseURL)
+	if err != nil {
+		return nil, err
+	}
+	protocols := make(map[string]bool)
+	for _, agentID := range autoAgents {
+		protocols[provider.ProtocolForAdapter(manifest.Agents[agentID].ConfigAdapter)] = true
+	}
+	ordered := make([]string, 0, len(protocols))
+	for protocolID := range protocols {
+		ordered = append(ordered, protocolID)
+	}
+	sort.Strings(ordered)
+	for _, protocolID := range ordered {
+		if u.provider == nil {
+			return nil, oneerrors.New(oneerrors.InternalError, "Provider probing is not configured", oneerrors.WithStatus(501))
+		}
+		verdict, err := u.provider.Probe(ctx, protocolID, "custom", options.APIKey, options.Model, target.BaseFor(protocolID))
+		if err != nil {
+			return nil, err
+		}
+		probes[protocolID] = verdict
+	}
+	u.sharpenInstallModelDiagnosis(ctx, probes, options)
+	return probes, nil
+}
+
+func (u *UseCases) sharpenInstallModelDiagnosis(ctx context.Context, probes map[string]provider.ProbeResult, options InstallAgentsOptions) {
+	failing := false
+	for _, verdict := range probes {
+		if !verdict.OK {
+			failing = true
+			break
+		}
+	}
+	if !failing || u.provider == nil {
+		return
+	}
+	target, err := u.providers.Resolve(options.Provider, options.APIBaseURL)
+	if err != nil {
+		return
+	}
+	listing, err := u.provider.ListModels(ctx, "custom", options.APIKey, target.BaseURL)
+	if err != nil || !listing.OK || len(listing.Models) == 0 {
+		return
+	}
+	if slices.Contains(listing.Models, options.Model) {
+		return
+	}
+	sample := listing.Models
+	if len(sample) > 5 {
+		sample = sample[:5]
+	}
+	for protocolID, verdict := range probes {
+		if verdict.OK {
+			continue
+		}
+		code := oneerrors.ModelsUnsupported
+		verdict.ErrorCode = &code
+		verdict.Retryable = false
+		verdict.Message = fmt.Sprintf("Model %q was not found in the endpoint's model list; the %s probe refused it. Available models include: %s.", options.Model, provider.ProtocolLabel(protocolID), strings.Join(sample, ", "))
+		probes[protocolID] = verdict
+	}
+}
+
+type installRun struct {
+	core         *UseCases
+	manifest     catalog.Manifest
+	options      InstallAgentsOptions
+	providerName string
+	probes       map[string]provider.ProbeResult
+	output       process.OutputListener
+	results      []AgentInstallResult
+	logs         []string
+	nextSteps    []string
+	firstCode    int
+}
+
+func (r *installRun) step(ctx context.Context, agentID string) {
+	agent := r.manifest.Agents[agentID]
+	if !contains(agent.Platforms, r.core.status.Platform.OS) {
+		r.fail(agentID, oneerrors.New(oneerrors.PrerequisiteMissing, fmt.Sprintf("%s is not supported on %s", agent.Name, r.core.status.Platform.OS)))
+		return
+	}
+	if agent.ConfigMode == "guide" {
+		guide := agent.Guide
+		r.results = append(r.results, AgentInstallResult{Agent: agentID, Status: "guide-only", Message: guide, Retryable: false})
+		r.logs = append(r.logs, "## "+agentID+"\nGuide only. "+guide)
+		r.nextSteps = append(r.nextSteps, guide)
+		return
+	}
+	if err := r.configure(ctx, agentID, agent); err != nil {
+		r.fail(agentID, err)
+	}
+}
+
+func (r *installRun) configure(ctx context.Context, agentID string, agent catalog.Agent) error {
+	// The managed runtime directories go on PATH before anything is looked up,
+	// so an npm or uv installed by an earlier OneAgent run is found instead of
+	// being reported missing and downloaded again.
+	runtime := r.core.installRuntime(nil)
+	runtime.OnOutput = func(output process.Output) {
+		output.Text = install.Redact(output.Text, []string{r.options.APIKey})
+		for index, argument := range output.Args {
+			output.Args[index] = install.Redact(argument, []string{r.options.APIKey})
+		}
+		if r.output != nil {
+			r.output(output)
+		}
+	}
+	installed := install.Result{Version: install.InstalledVersion(ctx, runtime, agent)}
+	if agent.Package != nil {
+		installed.LockedVersion = agent.Package.Version
+	}
+	if r.options.InstallAgent {
+		// Install the package manager this Agent needs before installing the
+		// Agent itself, otherwise a machine without Node or uv fails on a
+		// prerequisite the user cannot resolve from this screen.
+		bootstrapped, err := r.ensureAgentRuntime(ctx, agentID, agent, runtime)
+		if err != nil {
+			return err
+		}
+		runtime = bootstrapped
+		result, err := install.InstallLockedAgent(ctx, runtime, agentID, agent, install.Options{
+			EnforceLocked: r.options.LockedVersion,
+			Latest:        r.options.Latest,
+			Timeout:       r.options.Timeout,
+			Registry:      r.options.Registry,
+		})
+		if err != nil {
+			return err
+		}
+		installed = result
+		if result.Registry != "" {
+			r.logs = append(r.logs, "## "+agentID+"\nregistry: "+result.Registry)
+		}
+	} else if agent.Command != "" {
+		if _, present := r.core.runner.LookPath(agent.Command); !present {
+			r.logs = append(r.logs, "## "+agentID+"\nofficial install: "+officialInstallCommand(agent))
+		}
+	}
+	if r.options.CheckAgentOnly {
+		_, present := r.core.runner.LookPath(agent.Command)
+		status := "skipped"
+		if (agent.Command != "" && present) || installed.Installed {
+			status = "installed"
+		}
+		r.results = append(r.results, installResultFor(agentID, status, "", installed, true))
+		r.logs = append(r.logs, "## "+agentID+"\nAgent check complete.")
+		return nil
+	}
+	configPathValue := ""
+	if r.options.Configure {
+		protocolID := provider.ProtocolForAdapter(agent.ConfigAdapter)
+		if verdict, found := r.probes[protocolID]; found && !verdict.OK {
+			code := pointerString(verdict.ErrorCode)
+			if code == "" {
+				code = oneerrors.ProviderUnreachable
+			}
+			failure := oneerrors.New(code, fmt.Sprintf("%s: %s", agent.Name, verdict.Message), oneerrors.WithRetryable(verdict.Retryable))
+			return failure
+		}
+		target, err := r.core.providers.Resolve(r.options.Provider, r.options.APIBaseURL)
+		if err != nil {
+			return err
+		}
+		configBase := target.BaseFor(protocolID)
+		configPathValue = configPath(r.core.status.Home, r.core.status.Platform.OS, agent)
+		if configPathValue == "" {
+			return oneerrors.New(oneerrors.ConfigWriteFailed, fmt.Sprintf("Managed Agent %s has no configuration path", agentID))
+		}
+		writer := configWriter.NewWriter(r.core.status.Home, r.core.status.Platform.OS, r.core.filesystem)
+		if err := writeManagedAgentConfig(ctx, writer, agentID, agent, configPathValue, r.providerName, configBase, r.options.APIKey, r.options.Model, r.options.SmallFastModel); err != nil {
+			return err
+		}
+		if _, err := r.core.profiles.WriteAgentBinding(ctx, agentID, profileStore.BindingWriteRequest{
+			Provider:   r.options.Provider,
+			BaseURL:    configBase,
+			Model:      r.options.Model,
+			ProfileRef: r.options.ProfileID,
+		}); err != nil {
+			return err
+		}
+	}
+	status := "skipped"
+	message := "Model configuration skipped"
+	if r.options.Configure {
+		status = "configured"
+		message = "Configured"
+	}
+	r.results = append(r.results, installResultFor(agentID, status, configPathValue, installed, false))
+	r.logs = append(r.logs, "## "+agentID+"\n"+message+".")
+	if next := nextStep(r.core.status.Platform.OS, agentID, agent, r.options.Model); next != "" {
+		r.nextSteps = append(r.nextSteps, next)
+	}
+	return nil
+}
+
+// ensureAgentRuntime installs the runtime that provides this Agent's package
+// manager when the command is not resolvable, and returns a runtime whose PATH
+// includes it. A manager already on the machine is left alone: OneAgent does
+// not replace a user's own Node or uv.
+func (r *installRun) ensureAgentRuntime(ctx context.Context, agentID string, agent catalog.Agent, runtime install.Runtime) (install.Runtime, error) {
+	if agent.Package == nil {
+		return runtime, nil
+	}
+	manager := agent.Package.Manager
+	if executable, present := runtime.Runner.LookPath(manager); present && executable != "" {
+		return runtime, nil
+	}
+	manifest, err := catalog.LoadEmbeddedRuntimes()
+	if err != nil {
+		return runtime, err
+	}
+	runtimeID, entry, known := install.RuntimeForCommand(manifest, manager)
+	if !known {
+		return runtime, nil
+	}
+	updated, installed, err := install.EnsureRuntime(ctx, runtime, r.core.httpDoer, runtimeID, entry)
+	if err != nil {
+		return runtime, err
+	}
+	if installed {
+		r.logs = append(r.logs, "## "+agentID+"\nruntime: installed "+entry.Name+" "+entry.Version)
+		// Record the new directory on the login PATH now rather than at the end
+		// of the run: a failure here must surface against the Agent that needed
+		// it, not silently leave the runtime off PATH for the next session.
+		if _, err := r.core.persistRuntimePath(ctx, updated, manifest); err != nil {
+			return updated, err
+		}
+	}
+	return updated, nil
+}
+
+func (r *installRun) fail(agentID string, err error) {
+	converted := oneerrors.As(err)
+	if r.firstCode == 0 {
+		r.firstCode = converted.ExitCode
+	}
+	r.results = append(r.results, AgentInstallResult{
+		Agent: agentID, Status: "failed", Code: converted.ExitCode,
+		ErrorCode: converted.Code, Message: converted.Message, Retryable: converted.Retryable,
+	})
+	r.logs = append(r.logs, "## "+agentID+"\n"+converted.Message)
+}
+
+func (r *installRun) finish(ctx context.Context, baseURL string) InstallAgentsResult {
+	chosen := chooseInstallProbe(r.probes)
+	for _, protocolID := range sortedProbeIDs(r.probes) {
+		verdict := r.probes[protocolID]
+		if verdict.OK {
+			continue
+		}
+		if r.firstCode == 0 {
+			r.firstCode = oneerrors.ExitCodes[pointerString(verdict.ErrorCode)]
+			if r.firstCode == 0 {
+				r.firstCode = oneerrors.ExitCodes[oneerrors.ProviderUnreachable]
+			}
+		}
+		r.logs = append(r.logs, "## provider ("+protocolID+")\n"+verdict.Message)
+	}
+	failed := false
+	for _, result := range r.results {
+		if result.Status == "failed" {
+			failed = true
+			break
+		}
+	}
+	probeOK := chosen == nil || chosen.OK
+	if !failed && probeOK && !r.options.CheckAgentOnly {
+		if _, err := r.core.profiles.WriteActive(ctx, profileStore.ActiveRequest{
+			ProfileID: r.options.ProfileID,
+			Agents:    r.options.ProfileAgents,
+			Configure: r.options.Configure,
+			Provider:  r.options.Provider,
+			BaseURL:   baseURL,
+			Model:     r.options.Model,
+			APIKey:    r.options.APIKey,
+		}); err != nil {
+			// Config files are the source of truth for running Agents; preserve
+			// them and surface profile bookkeeping failure in the redacted log.
+			r.logs = append(r.logs, "## profile\n"+oneerrors.As(err).Message)
+		}
+	}
+	return InstallAgentsResult{
+		OK:      !failed && probeOK,
+		Code:    r.firstCode,
+		Results: r.results,
+		Log:     install.Redact(strings.Join(r.logs, "\n\n"), []string{r.options.APIKey}),
+		Next:    strings.Join(r.nextSteps, "\n"),
+		Probe:   chosen,
+		Probes:  r.probes,
+	}
+}
+
+func installResultFor(agentID, status, path string, installed install.Result, checkOnly bool) AgentInstallResult {
+	return AgentInstallResult{
+		Agent:         agentID,
+		Status:        status,
+		Config:        path,
+		Installed:     installed.Installed,
+		Version:       installed.Version,
+		LockedVersion: installed.LockedVersion,
+		Registry:      installed.Registry,
+		Retryable:     false,
+		checkOnly:     checkOnly,
+	}
+}
+
+func officialInstallCommand(agent catalog.Agent) string {
+	if agent.Package == nil {
+		return "Unsupported package manager: missing"
+	}
+	switch agent.Package.Manager {
+	case "npm":
+		return "npm install -g " + agent.Package.Name + "@" + agent.Package.Version
+	case "uv":
+		return "uv tool install --force --python python3.12 --no-python-downloads " + agent.Package.Name + "==" + agent.Package.Version
+	default:
+		manager := agent.Package.Manager
+		if manager == "" {
+			manager = "missing"
+		}
+		return "Unsupported package manager: " + manager
+	}
+}
+
+func chooseInstallProbe(probes map[string]provider.ProbeResult) *provider.ProbeResult {
+	var chosen *provider.ProbeResult
+	for _, protocolID := range sortedProbeIDs(probes) {
+		verdict := probes[protocolID]
+		if chosen == nil || (!verdict.OK && chosen.OK) {
+			copy := verdict
+			chosen = &copy
+		}
+	}
+	return chosen
+}
+
+func sortedProbeIDs(probes map[string]provider.ProbeResult) []string {
+	ids := make([]string, 0, len(probes))
+	for id := range probes {
+		ids = append(ids, id)
+	}
+	sort.Strings(ids)
+	return ids
+}
+
+func pointerString(value *string) string {
+	if value == nil {
+		return ""
+	}
+	return *value
+}
diff --git a/internal/app/install_test.go b/internal/app/install_test.go
new file mode 100644
index 00000000..d1cfe1cb
--- /dev/null
+++ b/internal/app/install_test.go
@@ -0,0 +1,229 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"maps"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+)
+
+func TestInstallResultWirePreservesFieldPresence(t *testing.T) {
+	configured, err := json.Marshal(AgentInstallResult{
+		Agent: "codex", Status: "configured", Config: "", Installed: false, LockedVersion: "0.145.0",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := string(configured), `{"agent":"codex","status":"configured","config":"","installed":false,"version":null,"lockedVersion":"0.145.0","retryable":false}`; got != want {
+		t.Fatalf("configured wire = %s, want %s", got, want)
+	}
+
+	checkOnly, err := json.Marshal(AgentInstallResult{
+		Agent: "codex", Status: "skipped", Installed: false, Version: "1.0.0", LockedVersion: "0.145.0", checkOnly: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := string(checkOnly), `{"agent":"codex","status":"skipped","installed":false,"version":"1.0.0","lockedVersion":"0.145.0","retryable":false}`; got != want {
+		t.Fatalf("check-only wire = %s, want %s", got, want)
+	}
+
+	guide, err := json.Marshal(AgentInstallResult{Agent: "gemini-cli", Status: "guide-only", Message: "use login"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := string(guide), `{"agent":"gemini-cli","status":"guide-only","message":"use login","retryable":false}`; got != want {
+		t.Fatalf("guide wire = %s, want %s", got, want)
+	}
+}
+
+type installAppRunner struct {
+	paths map[string]string
+	calls [][]string
+	envs  []map[string]string
+}
+
+func (r *installAppRunner) LookPath(command string) (string, bool) {
+	path, ok := r.paths[command]
+	return path, ok
+}
+
+func (r *installAppRunner) Run(_ context.Context, argv []string, env map[string]string, _ time.Duration) (process.Result, error) {
+	r.calls = append(r.calls, append([]string(nil), argv...))
+	copyEnv := make(map[string]string, len(env))
+	maps.Copy(copyEnv, env)
+	r.envs = append(r.envs, copyEnv)
+	if strings.Contains(strings.Join(argv, " "), "dist.integrity") {
+		return process.Result{Args: argv, ExitCode: 0, Stdout: "sha512-test\n"}, nil
+	}
+	if len(argv) > 1 && argv[1] == "--version" {
+		return process.Result{Args: argv, ExitCode: 0, Stdout: "tool 1.0.0"}, nil
+	}
+	return process.Result{Args: argv, ExitCode: 0}, nil
+}
+
+type installAppDoer func(*http.Request) (*http.Response, error)
+
+func (d installAppDoer) Do(request *http.Request) (*http.Response, error) { return d(request) }
+
+func installAppResponse(status int, body string) *http.Response {
+	return &http.Response{StatusCode: status, Body: io.NopCloser(strings.NewReader(body)), Header: make(http.Header)}
+}
+
+func installCore(t *testing.T, home string, runner process.Runner, doer provider.HTTPDoer) *UseCases {
+	t.Helper()
+	return NewUseCasesWithProviderClient(StatusOptions{
+		Home:        home,
+		Platform:    platform.For("linux", "amd64"),
+		Runner:      runner,
+		Environment: map[string]string{"HOME": home},
+	}, provider.NewClient(doer))
+}
+
+func installOptions(agents ...string) InstallAgentsOptions {
+	return InstallAgentsOptions{
+		Agents: agents, Provider: "ppio", APIKey: "install-secret", Model: "model-a",
+		Configure: true, SkipTest: true, Timeout: 30 * time.Second,
+	}
+}
+
+func TestInstallAgentsWritesAllManagedAdaptersAndPublishesProfileLast(t *testing.T) {
+	home := t.TempDir()
+	runner := &installAppRunner{paths: map[string]string{
+		"codex": "/fake/codex", "claude": "/fake/claude", "opencode": "/fake/opencode",
+		"kilo": "/fake/kilo", "aider": "/fake/aider", "npm": "/fake/npm", "uv": "/fake/uv",
+	}}
+	core := installCore(t, home, runner, installAppDoer(func(*http.Request) (*http.Response, error) {
+		return installAppResponse(http.StatusNoContent, ""), nil
+	}))
+	result, err := core.InstallAgents(context.Background(), installOptions("codex", "claude-code", "opencode", "kilo-cli", "aider"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !result.OK || len(result.Results) != 5 {
+		t.Fatalf("install result = %#v", result)
+	}
+	for _, item := range result.Results {
+		if item.Status != "configured" || item.Config == "" {
+			t.Errorf("result = %#v", item)
+		}
+	}
+	for _, path := range []string{
+		filepath.Join(home, ".codex", "config.toml"),
+		filepath.Join(home, ".claude", "settings.json"),
+		filepath.Join(home, ".config", "opencode", "opencode.jsonc"),
+		filepath.Join(home, ".config", "kilo", "kilo.jsonc"),
+		filepath.Join(home, ".oneagent", "aider.env"),
+		filepath.Join(home, ".oneagent", "profile.json"),
+	} {
+		if _, err := os.Stat(path); err != nil {
+			t.Errorf("expected file %s: %v", path, err)
+		}
+	}
+	if strings.Contains(result.Log, "install-secret") || strings.Contains(result.Next, "install-secret") {
+		t.Fatal("API key leaked through install result")
+	}
+	active := core.profiles.LoadActive()
+	if active.Profile == nil || active.ID != "default" || len(active.Profile.AgentIDs) != 5 {
+		t.Fatalf("active profile = %#v", active)
+	}
+	if binding, err := core.profiles.ReadAgentBinding("codex"); err != nil || binding == nil || binding.ProfileRef != "default" {
+		t.Fatalf("default profile binding = %#v, %v", binding, err)
+	}
+}
+
+func TestInstallAgentsAppliesNamedProfileWithItsSavedKey(t *testing.T) {
+	home := t.TempDir()
+	runner := &installAppRunner{paths: map[string]string{"codex": "/fake/codex"}}
+	core := installCore(t, home, runner, nil)
+	if _, err := core.SaveProfile(context.Background(), SaveProfileOptions{
+		ID: "team", Label: "Team", Provider: "ppio", APIKey: "profile-secret", Model: "model-a", AgentIDs: []string{"codex"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	options := installOptions("codex")
+	options.APIKey = ""
+	options.ProfileID = "team"
+	result, err := core.InstallAgents(context.Background(), options)
+	if err != nil || !result.OK {
+		t.Fatalf("named profile install = %#v, %v", result, err)
+	}
+	active := core.profiles.LoadActive()
+	binding, bindingErr := core.profiles.ReadAgentBinding("codex")
+	if active.ID != "team" || bindingErr != nil || binding == nil || binding.ProfileRef != "team" {
+		t.Fatalf("named profile state = active %#v, binding %#v, %v", active, binding, bindingErr)
+	}
+	env, err := os.ReadFile(filepath.Join(home, ".oneagent", "agents", "codex.env"))
+	if err != nil || !strings.Contains(string(env), "profile-secret") {
+		t.Fatalf("named profile credential was not applied: %q, %v", env, err)
+	}
+}
+
+func TestInstallAgentsRefusesInvalidRequestBeforeWriting(t *testing.T) {
+	home := t.TempDir()
+	runner := &installAppRunner{paths: map[string]string{"codex": "/fake/codex"}}
+	core := installCore(t, home, runner, nil)
+	options := installOptions("codex")
+	options.LockedVersion = true
+	options.Latest = true
+	if _, err := core.InstallAgents(context.Background(), options); err == nil {
+		t.Fatal("invalid request unexpectedly succeeded")
+	}
+	entries, err := os.ReadDir(home)
+	if err != nil && !os.IsNotExist(err) {
+		t.Fatal(err)
+	}
+	if len(entries) != 0 {
+		t.Fatalf("invalid request left files: %v", entries)
+	}
+}
+
+func TestInstallAgentsDoesNotPublishProfileWhenProbeFails(t *testing.T) {
+	home := t.TempDir()
+	runner := &installAppRunner{paths: map[string]string{"codex": "/fake/codex"}}
+	core := installCore(t, home, runner, installAppDoer(func(*http.Request) (*http.Response, error) {
+		return installAppResponse(http.StatusUnauthorized, `{"error":"bad key"}`), nil
+	}))
+	options := installOptions("codex")
+	options.SkipTest = false
+	result, err := core.InstallAgents(context.Background(), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.OK || len(result.Results) != 1 || result.Results[0].Status != "failed" {
+		t.Fatalf("failed install result = %#v", result)
+	}
+	if active := core.profiles.LoadActive(); active.Profile != nil || active.ID != "" {
+		t.Fatalf("failed install published active profile: %#v", active)
+	}
+}
+
+func TestInstallAgentsSharpenModelDiagnosis(t *testing.T) {
+	home := t.TempDir()
+	runner := &installAppRunner{paths: map[string]string{"codex": "/fake/codex"}}
+	core := installCore(t, home, runner, installAppDoer(func(request *http.Request) (*http.Response, error) {
+		if request.Method == http.MethodGet {
+			return installAppResponse(http.StatusOK, `{"data":[{"id":"real-model"}]}`), nil
+		}
+		return installAppResponse(http.StatusNotFound, ""), nil
+	}))
+	options := installOptions("codex")
+	options.SkipTest = false
+	result, err := core.InstallAgents(context.Background(), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Probe == nil || pointerString(result.Probe.ErrorCode) != "MODELS_UNSUPPORTED" || !strings.Contains(result.Probe.Message, "real-model") {
+		t.Fatalf("diagnosis = %#v", result.Probe)
+	}
+}
diff --git a/internal/app/install_wire.go b/internal/app/install_wire.go
new file mode 100644
index 00000000..816a403b
--- /dev/null
+++ b/internal/app/install_wire.go
@@ -0,0 +1,52 @@
+package app
+
+import "github.com/MaimoryLab/OneAgent/internal/jsonorder"
+
+// IsCheckOnly reports whether this result came from the agent-presence check
+// path. It is intentionally a method rather than a serialized field: the
+// transport adapters need the distinction to preserve the established field
+// presence, while clients should only see the public result shape.
+func (r AgentInstallResult) IsCheckOnly() bool {
+	return r.checkOnly
+}
+
+// MarshalJSON preserves the established install response's field presence and
+// insertion order. The distinction matters to clients: a normal automatic
+// result reports installed=false and version=null, while guide and failed
+// results do not pretend those fields exist.
+func (r AgentInstallResult) MarshalJSON() ([]byte, error) {
+	document := jsonorder.NewObject()
+	document.Set("agent", r.Agent)
+	document.Set("status", r.Status)
+
+	automatic := r.Status == "configured" || r.Status == "skipped" || r.Status == "installed"
+	if automatic {
+		if !r.checkOnly {
+			document.Set("config", r.Config)
+		}
+		document.Set("installed", r.Installed)
+		if r.Version == "" {
+			document.Set("version", nil)
+		} else {
+			document.Set("version", r.Version)
+		}
+		if r.LockedVersion == "" {
+			document.Set("lockedVersion", nil)
+		} else {
+			document.Set("lockedVersion", r.LockedVersion)
+		}
+		if r.Registry != "" {
+			document.Set("registry", r.Registry)
+		}
+	}
+	switch r.Status {
+	case "failed":
+		document.Set("code", r.Code)
+		document.Set("error_code", r.ErrorCode)
+		document.Set("message", r.Message)
+	case "guide-only":
+		document.Set("message", r.Message)
+	}
+	document.Set("retryable", r.Retryable)
+	return document.MarshalJSON()
+}
diff --git a/internal/app/provider.go b/internal/app/provider.go
new file mode 100644
index 00000000..9a207d3e
--- /dev/null
+++ b/internal/app/provider.go
@@ -0,0 +1,170 @@
+package app
+
+import (
+	"context"
+	"sort"
+	"strings"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+)
+
+type ProviderProbeOptions struct {
+	Provider   string
+	APIBaseURL string
+	APIKey     string
+	Model      string
+	AgentIDs   []string
+}
+
+type ProviderProbeResult struct {
+	Primary   provider.ProbeResult
+	Protocols map[string]provider.ProbeResult
+}
+
+func (u *UseCases) ProbeProvider(ctx context.Context, options ProviderProbeOptions) (ProviderProbeResult, error) {
+	if err := ctx.Err(); err != nil {
+		return ProviderProbeResult{}, oneerrors.New(oneerrors.Timeout, "Request was cancelled", oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+	}
+	if u == nil || u.provider == nil {
+		return ProviderProbeResult{}, oneerrors.New(oneerrors.InternalError, "Provider probing is not configured", oneerrors.WithStatus(501))
+	}
+	target, err := u.providers.Resolve(options.Provider, options.APIBaseURL)
+	if err != nil {
+		return ProviderProbeResult{}, err
+	}
+	apiKey := options.APIKey
+	if apiKey == "" {
+		apiKey = target.APIKey
+	}
+	model, err := u.resolveProviderModel(ctx, target, apiKey, options.Model)
+	if err != nil {
+		return ProviderProbeResult{}, err
+	}
+	protocols, err := protocolsForAgents(options.AgentIDs)
+	if err != nil {
+		return ProviderProbeResult{}, err
+	}
+	results := make(map[string]provider.ProbeResult, len(protocols))
+	for _, protocolID := range protocols {
+		result, probeErr := u.provider.Probe(ctx, protocolID, "custom", apiKey, model, target.BaseFor(protocolID))
+		if probeErr != nil {
+			return ProviderProbeResult{}, probeErr
+		}
+		results[protocolID] = result
+	}
+	primary := results[protocols[0]]
+	allOK := true
+	for _, protocolID := range protocols {
+		result := results[protocolID]
+		if !result.OK {
+			allOK = false
+			primary = result
+			break
+		}
+	}
+	primary.OK = allOK
+	return ProviderProbeResult{Primary: primary, Protocols: results}, nil
+}
+
+func (u *UseCases) ListProviderModels(ctx context.Context, providerID, apiKey, customBase string) (provider.ModelsResult, error) {
+	if err := ctx.Err(); err != nil {
+		return provider.ModelsResult{}, oneerrors.New(oneerrors.Timeout, "Request was cancelled", oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+	}
+	if u == nil || u.provider == nil {
+		return provider.ModelsResult{}, oneerrors.New(oneerrors.InternalError, "Model discovery is not configured", oneerrors.WithStatus(501))
+	}
+	target, err := u.providers.Resolve(providerID, customBase)
+	if err != nil {
+		return provider.ModelsResult{}, err
+	}
+	if apiKey == "" {
+		apiKey = target.APIKey
+	}
+	return u.provider.ListModels(ctx, "custom", apiKey, target.BaseURL)
+}
+
+func (u *UseCases) GetProvider(ctx context.Context, providerID string) (provider.Entry, error) {
+	if u == nil {
+		return provider.Entry{}, oneerrors.New(oneerrors.InternalError, "Provider service is not configured", oneerrors.WithStatus(501))
+	}
+	if err := contextError(ctx, "Provider request was cancelled"); err != nil {
+		return provider.Entry{}, err
+	}
+	return u.providers.Get(providerID)
+}
+
+func (u *UseCases) SaveProvider(ctx context.Context, entry provider.Entry) (provider.Entry, error) {
+	if u == nil {
+		return provider.Entry{}, oneerrors.New(oneerrors.InternalError, "Provider service is not configured", oneerrors.WithStatus(501))
+	}
+	if err := contextError(ctx, "Provider request was cancelled"); err != nil {
+		return provider.Entry{}, err
+	}
+	u.writeMu.Lock()
+	defer u.writeMu.Unlock()
+	return u.providers.Save(ctx, entry)
+}
+
+func (u *UseCases) DeleteProvider(ctx context.Context, providerID string) error {
+	if u == nil {
+		return oneerrors.New(oneerrors.InternalError, "Provider service is not configured", oneerrors.WithStatus(501))
+	}
+	if err := contextError(ctx, "Provider request was cancelled"); err != nil {
+		return err
+	}
+	u.writeMu.Lock()
+	defer u.writeMu.Unlock()
+	return u.providers.Delete(ctx, providerID)
+}
+
+func (u *UseCases) resolveProviderModel(ctx context.Context, target provider.Entry, apiKey, model string) (string, error) {
+	if model = strings.TrimSpace(model); model != "" {
+		return model, nil
+	}
+	if apiKey == "" {
+		return target.FallbackModel, nil
+	}
+	listing, err := u.provider.ListModels(ctx, "custom", apiKey, target.BaseURL)
+	if err != nil {
+		return "", err
+	}
+	if listing.OK && len(listing.Models) > 0 {
+		return provider.PickChatModel(listing.Models), nil
+	}
+	return target.FallbackModel, nil
+}
+
+func protocolsForAgents(agentIDs []string) ([]string, error) {
+	protocols := map[string]bool{}
+	if len(agentIDs) == 0 {
+		protocols[provider.ProtocolOpenAI] = true
+	} else {
+		manifest, err := catalog.LoadEmbedded()
+		if err != nil {
+			return nil, err
+		}
+		for _, agentID := range agentIDs {
+			if agentID == "" {
+				return nil, oneerrors.New(oneerrors.InvalidRequest, "agents must be a non-empty array of Agent IDs")
+			}
+			agent, ok := manifest.Agents[agentID]
+			if !ok {
+				return nil, oneerrors.New(oneerrors.InvalidRequest, "Unknown Agent: "+agentID)
+			}
+			if agent.ConfigMode == "auto" {
+				protocols[provider.ProtocolForAdapter(agent.ConfigAdapter)] = true
+			}
+		}
+		if len(protocols) == 0 {
+			protocols[provider.ProtocolOpenAI] = true
+		}
+	}
+	result := make([]string, 0, len(protocols))
+	for protocolID := range protocols {
+		result = append(result, protocolID)
+	}
+	sort.Strings(result)
+	return result, nil
+}
diff --git a/internal/app/provider_test.go b/internal/app/provider_test.go
new file mode 100644
index 00000000..4ce39990
--- /dev/null
+++ b/internal/app/provider_test.go
@@ -0,0 +1,135 @@
+package app
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"reflect"
+	"sort"
+	"strings"
+	"testing"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+)
+
+type appProviderDoer func(*http.Request) (*http.Response, error)
+
+func (doer appProviderDoer) Do(request *http.Request) (*http.Response, error) {
+	return doer(request)
+}
+
+func appProviderResponse(status int, body string) *http.Response {
+	return &http.Response{StatusCode: status, Body: io.NopCloser(strings.NewReader(body)), Header: make(http.Header)}
+}
+
+func providerUseCases(t *testing.T, doer provider.HTTPDoer) *UseCases {
+	t.Helper()
+	return NewUseCasesWithProviderClient(StatusOptions{
+		Home:     t.TempDir(),
+		Platform: platform.For("linux", "amd64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	}, provider.NewClient(doer))
+}
+
+func TestProbeProviderAggregatesAgentProtocols(t *testing.T) {
+	seen := make([]string, 0)
+	core := providerUseCases(t, appProviderDoer(func(request *http.Request) (*http.Response, error) {
+		seen = append(seen, request.URL.Path)
+		return appProviderResponse(http.StatusNoContent, ""), nil
+	}))
+	result, err := core.ProbeProvider(context.Background(), ProviderProbeOptions{
+		Provider:   "custom",
+		APIBaseURL: "https://proxy.test/v1",
+		APIKey:     "key",
+		Model:      "model",
+		AgentIDs:   []string{"codex", "claude-code", "opencode"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !result.Primary.OK || len(result.Protocols) != 3 || result.Primary.Protocol == nil || *result.Primary.Protocol != provider.ProtocolAnthropic {
+		t.Fatalf("aggregated probe = %#v", result)
+	}
+	sort.Strings(seen)
+	if !reflect.DeepEqual(seen, []string{"/v1/chat/completions", "/v1/messages", "/v1/responses"}) {
+		t.Fatalf("probe paths = %v", seen)
+	}
+}
+
+func TestProbeProviderSelectsFirstFailure(t *testing.T) {
+	core := providerUseCases(t, appProviderDoer(func(request *http.Request) (*http.Response, error) {
+		if request.URL.Path == "/v1/responses" {
+			return appProviderResponse(http.StatusBadRequest, `{"message":"does not support endpoint"}`), nil
+		}
+		return appProviderResponse(http.StatusNoContent, ""), nil
+	}))
+	result, err := core.ProbeProvider(context.Background(), ProviderProbeOptions{
+		Provider: "custom", APIBaseURL: "https://proxy.test/v1", APIKey: "key", Model: "model", AgentIDs: []string{"codex", "opencode"},
+	})
+	if err != nil || result.Primary.OK || result.Primary.ErrorCode == nil || *result.Primary.ErrorCode != oneerrors.ProtocolUnsupported {
+		t.Fatalf("failure result = %#v, err=%v", result, err)
+	}
+}
+
+func TestProtocolsForAgentsRejectsUnknownAndIgnoresGuideOnly(t *testing.T) {
+	protocols, err := protocolsForAgents([]string{"openclaw"})
+	if err != nil || !reflect.DeepEqual(protocols, []string{provider.ProtocolOpenAI}) {
+		t.Fatalf("guide protocols = %v, err=%v", protocols, err)
+	}
+	if _, err := protocolsForAgents([]string{"missing-agent"}); err == nil || oneerrors.As(err).Code != oneerrors.InvalidRequest {
+		t.Fatalf("unknown Agent error = %v", err)
+	}
+	if _, err := protocolsForAgents([]string{""}); err == nil || oneerrors.As(err).Code != oneerrors.InvalidRequest {
+		t.Fatalf("empty Agent error = %v", err)
+	}
+}
+
+func TestProviderUseCasesHonorCancellationBeforeNetwork(t *testing.T) {
+	called := false
+	core := providerUseCases(t, appProviderDoer(func(*http.Request) (*http.Response, error) {
+		called = true
+		return appProviderResponse(http.StatusOK, `{}`), nil
+	}))
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err := core.ListProviderModels(ctx, "ppio", "key", "")
+	if err == nil || oneerrors.As(err).Code != oneerrors.Timeout || called {
+		t.Fatalf("cancelled call = %v, called=%v", err, called)
+	}
+}
+
+func TestSavedProviderDrivesStatusAndProbeWithoutResendingKey(t *testing.T) {
+	home := t.TempDir()
+	var request *http.Request
+	client := provider.NewClient(appProviderDoer(func(value *http.Request) (*http.Response, error) {
+		request = value
+		return appProviderResponse(http.StatusNoContent, ""), nil
+	}))
+	options := StatusOptions{
+		Home: home, Platform: platform.For("linux", "amd64"),
+		Lookup: func(string) (string, bool) { return "", false },
+	}
+	core := NewUseCasesWithProviderClient(options, client)
+	if _, err := core.SaveProvider(context.Background(), provider.Entry{
+		ID: "acme", Name: "Acme", BaseURL: "https://api.acme.test/openai", APIKey: "saved-key",
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	reloaded := NewUseCasesWithProviderClient(options, client)
+	status, err := reloaded.GetStatus(context.Background())
+	if err != nil || !status.Providers["acme"].Custom || !status.Providers["acme"].HasKey {
+		t.Fatalf("saved Provider status = %#v, err=%v", status.Providers["acme"], err)
+	}
+	result, err := reloaded.ProbeProvider(context.Background(), ProviderProbeOptions{
+		Provider: "acme", Model: "model-a", AgentIDs: []string{"opencode"},
+	})
+	if err != nil || !result.Primary.OK {
+		t.Fatalf("saved Provider probe = %#v, err=%v", result, err)
+	}
+	if request == nil || request.URL.Host != "api.acme.test" || request.Header.Get("Authorization") != "Bearer saved-key" {
+		t.Fatalf("saved Provider request = %#v", request)
+	}
+}
diff --git a/internal/app/runtime.go b/internal/app/runtime.go
new file mode 100644
index 00000000..c08ed05e
--- /dev/null
+++ b/internal/app/runtime.go
@@ -0,0 +1,250 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/install"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+)
+
+// RuntimeStatus is the public projection of one bootstrappable runtime.
+type RuntimeStatus = install.RuntimeState
+
+// InstallRuntimeOptions is one runtime bootstrap request.
+type InstallRuntimeOptions struct {
+	RuntimeID string
+	Timeout   time.Duration
+	Output    process.OutputListener
+}
+
+// InstallRuntimeResult reports what the bootstrap did. PathUpdated is separate
+// from Installed because an already-downloaded runtime may still need its
+// directory recorded on the login PATH.
+type InstallRuntimeResult struct {
+	Runtime     string        `json:"runtime"`
+	Installed   bool          `json:"installed"`
+	Version     string        `json:"version"`
+	PathUpdated bool          `json:"pathUpdated"`
+	Runtimes    []RuntimeStatus `json:"runtimes"`
+}
+
+// RuntimeStatuses reports every runtime in the lock file for this platform.
+func (u *UseCases) RuntimeStatuses(ctx context.Context) ([]RuntimeStatus, error) {
+	if u == nil {
+		return nil, oneerrors.New(oneerrors.InternalError, "Runtime service is not configured", oneerrors.WithStatus(501))
+	}
+	if _, err := catalog.LoadEmbeddedRuntimes(); err != nil {
+		return nil, err
+	}
+	states, _ := u.runtimeCapability(ctx)
+	return states, nil
+}
+
+// InstallRuntime downloads and installs one locked runtime, then records its
+// directory on the login PATH so the user's own terminal and later OneAgent
+// runs both resolve it.
+func (u *UseCases) InstallRuntime(ctx context.Context, options InstallRuntimeOptions) (InstallRuntimeResult, error) {
+	if u == nil {
+		return InstallRuntimeResult{}, oneerrors.New(oneerrors.InternalError, "Runtime service is not configured", oneerrors.WithStatus(501))
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if err := contextError(ctx, "Runtime installation request was cancelled"); err != nil {
+		return InstallRuntimeResult{}, err
+	}
+	manifest, err := catalog.LoadEmbeddedRuntimes()
+	if err != nil {
+		return InstallRuntimeResult{}, err
+	}
+	entry, present := manifest.Runtimes[options.RuntimeID]
+	if !present {
+		return InstallRuntimeResult{}, oneerrors.New(oneerrors.InvalidRequest, "Unknown runtime: "+options.RuntimeID)
+	}
+
+	// The bootstrap writes into the OneAgent home and touches shell profiles;
+	// keep it under the same coordinator as Agent installs so two requests
+	// cannot interleave a profile rewrite.
+	u.writeMu.Lock()
+	defer u.writeMu.Unlock()
+
+	runtime := u.installRuntime(options.Output)
+	updated, installed, err := install.EnsureRuntime(ctx, runtime, u.httpDoer, options.RuntimeID, entry)
+	if err != nil {
+		return InstallRuntimeResult{}, err
+	}
+	pathUpdated, err := u.persistRuntimePath(ctx, updated, manifest)
+	if err != nil {
+		return InstallRuntimeResult{}, err
+	}
+	// Report status through the updated runtime so the freshly installed
+	// directory is on the PATH used for the version probe.
+	states := install.RuntimeStates(ctx, updated, manifest)
+	result := InstallRuntimeResult{
+		Runtime:     options.RuntimeID,
+		Installed:   installed,
+		PathUpdated: pathUpdated,
+		Runtimes:    states,
+	}
+	for _, state := range states {
+		if state.ID == options.RuntimeID {
+			result.Version = state.Version
+			break
+		}
+	}
+	return result, nil
+}
+
+func (u *UseCases) persistRuntimePath(ctx context.Context, runtime install.Runtime, manifest catalog.RuntimeManifest) (bool, error) {
+	dirs := install.ManagedPathDirs(u.status.Home, u.status.Platform.OS, u.status.Platform.Arch, manifest)
+	if len(dirs) == 0 {
+		return false, nil
+	}
+	return install.PersistRuntimePath(ctx, runtime, u.filesystem, dirs)
+}
+
+// installRuntime builds the process runtime with managed directories already on
+// PATH. Every caller that runs npm or uv must go through this so a runtime
+// installed in an earlier session is found instead of reinstalled.
+func (u *UseCases) installRuntime(output process.OutputListener) install.Runtime {
+	runtime := install.NewRuntime(u.status.Home, u.status.Platform, u.runner, u.environment)
+	runtime.OnOutput = output
+	manifest, err := catalog.LoadEmbeddedRuntimes()
+	if err != nil {
+		return runtime
+	}
+	for _, directory := range install.ManagedPathDirs(u.status.Home, u.status.Platform.OS, u.status.Platform.Arch, manifest) {
+		runtime = install.WithManagedPath(runtime, directory)
+	}
+	return runtime
+}
+
+// runtimeCapability reads runtime state once for GetStatus and returns a lookup
+// that answers two questions per package manager: is the command available now,
+// and if not, can OneAgent install the runtime that provides it.
+func (u *UseCases) runtimeCapability(ctx context.Context) ([]RuntimeStatus, runtimeCapabilityLookup) {
+	manifest, err := catalog.LoadEmbeddedRuntimes()
+	if err != nil {
+		return nil, runtimeCapabilityLookup{}
+	}
+	// Status must resolve commands in the same environment installs run in, so
+	// resolution goes through the managed-PATH runner. An injected Lookup still
+	// wins: it is the seam that keeps status reproducible in tests and keeps a
+	// developer's own Node out of a test's answer.
+	runtime := u.installRuntime(nil)
+	if u.status.Lookup != nil {
+		runtime.Runner = statusRunner{Runner: runtime.Runner, lookup: u.status.Lookup}
+	}
+	states := install.RuntimeStates(ctx, runtime, manifest)
+	agents, agentErr := catalog.LoadEmbedded()
+	byCommand := make(map[string]RuntimeStatus, len(states)*2)
+	for index, state := range states {
+		if agentErr == nil {
+			states[index].RequiredByHint = requiredByHint(manifest, agents, state.ID, u.status.Platform.OS)
+		}
+		for _, command := range manifest.Runtimes[state.ID].Commands {
+			byCommand[command] = states[index]
+		}
+	}
+	return states, runtimeCapabilityLookup{byCommand: byCommand, resolve: runtime.Runner.LookPath}
+}
+
+// statusRunner routes command resolution through the status Lookup while
+// keeping the real runner for version probes.
+type statusRunner struct {
+	process.Runner
+	lookup CommandLookup
+}
+
+func (r statusRunner) LookPath(command string) (string, bool) {
+	return r.lookup(command)
+}
+
+type runtimeCapabilityLookup struct {
+	byCommand map[string]RuntimeStatus
+	// resolve is the managed-PATH resolver, the same one status used to probe
+	// runtime versions. GetStatus reuses it so an Agent CLI installed under the
+	// managed global prefix is found, not just the runtimes themselves.
+	resolve CommandLookup
+}
+
+// available reports whether this package manager can be executed. A managed
+// runtime counts even when the host PATH has no such command, because installs
+// run with the managed directory prepended.
+func (l runtimeCapabilityLookup) available(manager string) bool {
+	if state, known := l.byCommand[manager]; known {
+		if state.Installed || state.Managed {
+			return true
+		}
+	}
+	return l.present(manager)
+}
+
+// present reports whether a command resolves the way an install would.
+func (l runtimeCapabilityLookup) present(command string) bool {
+	_, ok := l.lookup(command)
+	return ok
+}
+
+// lookup resolves a command the way an install would. It answers false rather
+// than falling back to the process PATH when no resolver was built, so status
+// cannot report a command OneAgent would not actually be able to run.
+func (l runtimeCapabilityLookup) lookup(command string) (string, bool) {
+	if l.resolve == nil || command == "" {
+		return "", false
+	}
+	return l.resolve(command)
+}
+
+// provider names the runtime that supplies this manager, when the current
+// platform has a locked download for it.
+func (l runtimeCapabilityLookup) provider(manager string) (string, bool) {
+	state, known := l.byCommand[manager]
+	if !known || !state.Supported {
+		return "", false
+	}
+	return state.ID, true
+}
+
+// requiredByHint names the Agents that cannot be installed without this
+// runtime, so the UI can explain why an install button matters.
+func requiredByHint(runtimes catalog.RuntimeManifest, agents catalog.Manifest, runtimeID, osID string) string {
+	entry := runtimes.Runtimes[runtimeID]
+	managers := make(map[string]bool, len(entry.Commands))
+	for _, command := range entry.Commands {
+		managers[command] = true
+	}
+	names := make([]string, 0, len(agents.Agents))
+	for _, id := range catalog.AgentIDs(agents) {
+		agent := agents.Agents[id]
+		if agent.Package == nil || !managers[agent.Package.Manager] {
+			continue
+		}
+		if !contains(agent.Platforms, osID) {
+			continue
+		}
+		names = append(names, agent.Name)
+	}
+	if len(names) == 0 {
+		return ""
+	}
+	if len(names) > 3 {
+		return fmt.Sprintf("%s, %s, %s +%d", names[0], names[1], names[2], len(names)-3)
+	}
+	return joinNames(names)
+}
+
+func joinNames(names []string) string {
+	switch len(names) {
+	case 1:
+		return names[0]
+	case 2:
+		return names[0] + ", " + names[1]
+	default:
+		return names[0] + ", " + names[1] + ", " + names[2]
+	}
+}
diff --git a/internal/app/runtime_test.go b/internal/app/runtime_test.go
new file mode 100644
index 00000000..1bfecd26
--- /dev/null
+++ b/internal/app/runtime_test.go
@@ -0,0 +1,232 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	"github.com/MaimoryLab/OneAgent/internal/install"
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+)
+
+// archiveDoer serves the locked artifact for one runtime from memory so the
+// bootstrap chain is exercised without reaching the network.
+type archiveDoer struct {
+	bodies map[string][]byte
+	hits   int
+}
+
+func (d *archiveDoer) Do(request *http.Request) (*http.Response, error) {
+	d.hits++
+	body, ok := d.bodies[request.URL.String()]
+	if !ok {
+		return &http.Response{StatusCode: http.StatusNotFound, Body: io.NopCloser(strings.NewReader("")), Request: request}, nil
+	}
+	return &http.Response{StatusCode: http.StatusOK, Body: io.NopCloser(bytes.NewReader(body)), Request: request}, nil
+}
+
+func TestRuntimeStatusesReportLockedVersionsAndRequirements(t *testing.T) {
+	home := t.TempDir()
+	core := NewUseCases(StatusOptions{
+		Home:     home,
+		Platform: platform.For("darwin", "arm64"),
+		Lookup:   func(command string) (string, bool) { return "", false },
+	})
+	states, err := core.RuntimeStatuses(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(states) != 2 {
+		t.Fatalf("expected node and uv, got %d", len(states))
+	}
+	byID := map[string]RuntimeStatus{}
+	for _, state := range states {
+		byID[state.ID] = state
+	}
+	node := byID["node"]
+	if node.Installed || node.Managed || !node.Supported {
+		t.Fatalf("node state on a bare machine = %#v", node)
+	}
+	if node.Command != "npm" || node.LockedVersion == "" {
+		t.Fatalf("node contract = %#v", node)
+	}
+	// The hint is what lets the UI explain why a runtime matters.
+	if !strings.Contains(node.RequiredByHint, "Codex") {
+		t.Fatalf("node requiredBy = %q", node.RequiredByHint)
+	}
+	if uv := byID["uv"]; uv.RequiredByHint != "Aider" {
+		t.Fatalf("uv requiredBy = %q", uv.RequiredByHint)
+	}
+}
+
+func TestStatusReportsBootstrappableRuntimeInsteadOfADeadEnd(t *testing.T) {
+	home := t.TempDir()
+	// Nothing on PATH: every npm and uv Agent is uninstallable, and each one must
+	// name the runtime that would fix it.
+	core := NewUseCases(StatusOptions{
+		Home:     home,
+		Platform: platform.For("darwin", "arm64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	})
+	status, err := core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if status.Capabilities.MissingRuntime["codex"] != "node" {
+		t.Fatalf("codex missing runtime = %q", status.Capabilities.MissingRuntime["codex"])
+	}
+	if status.Capabilities.MissingRuntime["aider"] != "uv" {
+		t.Fatalf("aider missing runtime = %q", status.Capabilities.MissingRuntime["aider"])
+	}
+	if status.Capabilities.CanInstall["codex"] {
+		t.Fatal("codex should not be installable without npm")
+	}
+	// A guide-only Agent has no package manager, so it must not be reported as
+	// blocked on a runtime.
+	if _, present := status.Capabilities.MissingRuntime["cline"]; present {
+		t.Fatal("a guide-only Agent should not claim a missing runtime")
+	}
+
+	// With npm present the Agent becomes installable and stops asking for Node.
+	withNPM := NewUseCases(StatusOptions{
+		Home:     home,
+		Platform: platform.For("darwin", "arm64"),
+		Lookup: func(command string) (string, bool) {
+			if command == "npm" {
+				return "/usr/local/bin/npm", true
+			}
+			return "", false
+		},
+	})
+	status, err = withNPM.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !status.Capabilities.CanInstall["codex"] {
+		t.Fatal("codex should be installable with npm present")
+	}
+	if _, present := status.Capabilities.MissingRuntime["codex"]; present {
+		t.Fatal("codex should not report a missing runtime when npm is present")
+	}
+}
+
+func TestManagedRuntimeIsReusedRatherThanReinstalled(t *testing.T) {
+	home := t.TempDir()
+	manifest, err := catalog.LoadEmbeddedRuntimes()
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := manifest.Runtimes["node"]
+	key := catalog.RuntimeArtifactKey("macos", "arm64")
+	artifact := entry.Artifacts[key]
+
+	// Simulate a tree installed by an earlier session, marker included.
+	binDir := filepath.Join(home, ".oneagent", "runtimes", "node", "v"+entry.Version, artifact.BinDir)
+	if err := os.MkdirAll(binDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(binDir, ".oneagent-runtime-ok"), []byte(entry.Version+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(binDir, "npm"), []byte("#!/bin/sh\necho 11.0.0\n"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+
+	core := NewUseCases(StatusOptions{
+		Home:        home,
+		Platform:    platform.For("darwin", "arm64"),
+		Environment: map[string]string{"HOME": home, "PATH": filepath.Join(home, "empty")},
+	})
+	// A downloader that fails on any request proves nothing was fetched.
+	core.SetRuntimeDownloader(&archiveDoer{bodies: map[string][]byte{}})
+	states, err := core.RuntimeStatuses(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, state := range states {
+		if state.ID != "node" {
+			continue
+		}
+		if !state.Managed || !state.Installed {
+			t.Fatalf("an existing managed tree was not detected: %#v", state)
+		}
+		if state.Version != "11.0.0" {
+			t.Fatalf("version probe ran outside the managed PATH: %#v", state)
+		}
+	}
+
+	// EnsureRuntime must return the existing tree without downloading.
+	runtime := install.NewRuntime(home, platform.For("darwin", "arm64"), process.New(map[string]string{"HOME": home, "PATH": filepath.Join(home, "empty")}), map[string]string{"HOME": home})
+	updated, installed, err := install.EnsureRuntime(context.Background(), runtime, core.httpDoer, "node", entry)
+	if err != nil || installed {
+		t.Fatalf("existing tree triggered a download: %v, %v", installed, err)
+	}
+	if resolved, ok := updated.Runner.LookPath("npm"); !ok || filepath.Dir(resolved) != binDir {
+		t.Fatalf("managed npm not resolvable: %q %v", resolved, ok)
+	}
+}
+
+// A managed runtime is only usable if status resolves commands in the same
+// environment installs run in. Resolving against the OneAgent process PATH
+// instead would report an Agent CLI under the managed global prefix as missing
+// and keep offering to install a runtime that is already there.
+func TestStatusResolvesAgentsInTheManagedEnvironment(t *testing.T) {
+	home := t.TempDir()
+	manifest, err := catalog.LoadEmbeddedRuntimes()
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := manifest.Runtimes["node"]
+	artifact := entry.Artifacts[catalog.RuntimeArtifactKey("macos", "arm64")]
+
+	// A managed node tree plus an Agent CLI in the global prefix, exactly the
+	// layout an npm install through OneAgent leaves behind.
+	binDir := filepath.Join(home, ".oneagent", "runtimes", "node", "v"+entry.Version, artifact.BinDir)
+	globalBin := install.GlobalBinDir(home, "macos")
+	for _, directory := range []string{binDir, globalBin} {
+		if err := os.MkdirAll(directory, 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := os.WriteFile(filepath.Join(binDir, ".oneagent-runtime-ok"), []byte(entry.Version+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(binDir, "npm"), []byte("#!/bin/sh\necho 11.0.0\n"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(globalBin, "codex"), []byte("#!/bin/sh\necho 0.9.9\n"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+
+	// PATH names a directory that does not exist, so anything reported as found
+	// had to come from the managed directories rather than from the host.
+	core := NewUseCases(StatusOptions{
+		Home:        home,
+		Platform:    platform.For("darwin", "arm64"),
+		Environment: map[string]string{"HOME": home, "PATH": filepath.Join(home, "empty")},
+	})
+	status, err := core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	codex := status.Agents["codex"]
+	if !codex.Installed {
+		t.Fatalf("an Agent in the managed global prefix was reported missing: %#v", codex)
+	}
+	if codex.Version == nil || *codex.Version != "0.9.9" {
+		t.Fatalf("version probe ran outside the managed PATH: %#v", codex.Version)
+	}
+	if !status.Capabilities.CanInstall["codex"] {
+		t.Fatal("npm from the managed tree should make codex installable")
+	}
+	if _, present := status.Capabilities.MissingRuntime["codex"]; present {
+		t.Fatal("a managed node tree should not be reported as a missing runtime")
+	}
+}
diff --git a/internal/app/status.go b/internal/app/status.go
new file mode 100644
index 00000000..e25fbae7
--- /dev/null
+++ b/internal/app/status.go
@@ -0,0 +1,564 @@
+// Package app contains transport-independent use cases shared by the desktop
+// binding and the headless CLI.
+package app
+
+import (
+	"context"
+	"maps"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	configReader "github.com/MaimoryLab/OneAgent/internal/config"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/install"
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+	profileStore "github.com/MaimoryLab/OneAgent/internal/profile"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+type CommandLookup func(string) (string, bool)
+
+type StatusOptions struct {
+	Home     string
+	Platform platform.Info
+	Lookup   CommandLookup
+	// FileSystem is optional and exists for tests or platform-specific hosts
+	// that need to inject ACL behavior. Production callers use the default
+	// securefs implementation for the selected platform.
+	FileSystem  *securefs.Store
+	Runner      process.Runner
+	Environment map[string]string
+}
+
+type UseCases struct {
+	status      StatusOptions
+	provider    *provider.Client
+	providers   provider.Store
+	profiles    profileStore.Store
+	filesystem  securefs.Store
+	runner      process.Runner
+	environment map[string]string
+	// httpDoer is only used for runtime archive downloads. It is injectable so
+	// bootstrap behavior is testable without reaching nodejs.org.
+	httpDoer install.Doer
+	writeMu  sync.Mutex
+}
+
+// SetRuntimeDownloader overrides the HTTP client used for runtime archive
+// downloads. It exists for tests and for hosts that must route downloads
+// through their own transport.
+func (u *UseCases) SetRuntimeDownloader(client install.Doer) {
+	if u != nil {
+		u.httpDoer = client
+	}
+}
+
+func NewUseCases(options StatusOptions) *UseCases {
+	return NewUseCasesWithProviderClient(options, nil)
+}
+
+// NewUseCasesWithProviderClient keeps network access injectable so Go behavior
+// can be verified with fake transports.
+func NewUseCasesWithProviderClient(options StatusOptions, client *provider.Client) *UseCases {
+	return newUseCases(options, client, profileStore.Store{})
+}
+
+func NewUseCasesWithDependencies(options StatusOptions, client *provider.Client, profiles profileStore.Store) *UseCases {
+	return newUseCases(options, client, profiles)
+}
+
+func newUseCases(options StatusOptions, client *provider.Client, profiles profileStore.Store) *UseCases {
+	if options.Platform.OS == "" {
+		options.Platform = platform.Current()
+	}
+	if options.Home == "" {
+		options.Home = platform.ResolveHome(nil, options.Platform.OS)
+	}
+	// Lookup stays nil unless a caller injected one. A default here would resolve
+	// against the OneAgent process PATH, which disagrees with the environment
+	// installs and version probes actually run in: a managed runtime and any
+	// Agent CLI under the managed global prefix would be reported missing.
+	// runtimeCapability supplies the managed-PATH lookup instead.
+	if options.Lookup == nil && options.Runner != nil {
+		options.Lookup = options.Runner.LookPath
+	}
+	if client == nil {
+		client = provider.NewClient(nil)
+	}
+	runner := options.Runner
+	if runner == nil {
+		current := process.Current()
+		runner = current
+		if options.Environment == nil {
+			options.Environment = current.Env
+		}
+	}
+	if options.Environment == nil {
+		options.Environment = map[string]string{}
+	}
+	if profiles.Home == "" {
+		profiles = profileStore.NewStore(options.Home, options.Platform.OS)
+	}
+	filesystem := securefs.New(securefs.Options{OS: options.Platform.OS})
+	if options.FileSystem != nil {
+		filesystem = *options.FileSystem
+		profiles.FS = &filesystem
+	} else if profiles.FS != nil {
+		// Reuse an injected profile filesystem so one operation has one
+		// security policy for profile, env, and Agent config writes.
+		filesystem = *profiles.FS
+	}
+	return &UseCases{
+		status:      options,
+		provider:    client,
+		providers:   provider.NewStore(options.Home, filesystem),
+		profiles:    profiles,
+		filesystem:  filesystem,
+		runner:      runner,
+		environment: cloneEnvironment(options.Environment),
+	}
+}
+
+func cloneEnvironment(source map[string]string) map[string]string {
+	result := make(map[string]string, len(source))
+	maps.Copy(result, source)
+	return result
+}
+
+func NewUseCasesFromEnvironment() *UseCases {
+	info := platform.Current()
+	return NewUseCases(StatusOptions{
+		Home:     platform.ResolveHome(nil, info.OS),
+		Platform: info,
+	})
+}
+
+type StatusResponse struct {
+	APIVersion       int                         `json:"apiVersion"`
+	Platform         platform.Info               `json:"platform"`
+	Capabilities     Capabilities                `json:"capabilities"`
+	Agents           map[string]AgentStatus      `json:"agents"`
+	Catalog          []catalog.CatalogItem       `json:"catalog"`
+	Groups           []catalog.Group             `json:"groups"`
+	Providers        map[string]catalog.Provider `json:"providers"`
+	Mirrors          []catalog.Mirror            `json:"mirrors"`
+	Paths            map[string]string           `json:"paths"`
+	Backups          map[string]bool             `json:"backups"`
+	Profiles         []ProfileSummary            `json:"profiles"`
+	ActiveProfile    *string                     `json:"activeProfile"`
+	Runtimes         []RuntimeStatus             `json:"runtimes"`
+	Environment      any                         `json:"environment"`
+	EnvironmentError *string                     `json:"environmentError"`
+}
+
+type Capabilities struct {
+	CanInstall map[string]bool `json:"canInstall"`
+	// MissingRuntime names the runtime an Agent needs before it can be
+	// installed, keyed by Agent id. An entry means canInstall is false only
+	// because a bootstrappable runtime is absent, which the UI turns into a
+	// "install the runtime first" prompt rather than a dead end.
+	MissingRuntime    map[string]string `json:"missingRuntime"`
+	SupportedAgentIDs []string          `json:"supportedAgentIds"`
+}
+
+type AgentStatus struct {
+	Installed     bool            `json:"installed"`
+	Configured    bool            `json:"configured"`
+	GuideOnly     bool            `json:"guideOnly"`
+	Config        string          `json:"config"`
+	Version       *string         `json:"version"`
+	LockedVersion *string         `json:"lockedVersion"`
+	CanInstall    bool            `json:"canInstall"`
+	Provider      *string         `json:"provider"`
+	ProfileID     *string         `json:"profileId"`
+	Model         *string         `json:"model"`
+	BaseURL       *string         `json:"baseUrl"`
+	UpdatedAt     *string         `json:"updatedAt"`
+	Detected      *DetectedConfig `json:"detected"`
+}
+
+type DetectedConfig struct {
+	BaseURL           string  `json:"baseUrl"`
+	Model             string  `json:"model"`
+	ManagedByOneAgent bool    `json:"managedByOneAgent"`
+	Unreadable        *string `json:"unreadable"`
+}
+
+// ProfileSummary is intentionally a public projection. It has no credential
+// field; hasKey only reports whether a secret exists in the secure store.
+type ProfileSummary struct {
+	ID          string   `json:"id"`
+	Label       string   `json:"label"`
+	Provider    string   `json:"provider"`
+	BaseURL     *string  `json:"baseUrl"`
+	Model       *string  `json:"model"`
+	AgentIDs    []string `json:"agentIds"`
+	ActivatedAt *string  `json:"activatedAt"`
+	HasKey      bool     `json:"hasKey"`
+}
+
+func (u *UseCases) GetStatus(ctx context.Context) (StatusResponse, error) {
+	if u == nil {
+		return StatusResponse{}, oneerrors.New(oneerrors.InternalError, "Status service is not configured", oneerrors.WithStatus(501))
+	}
+	if err := ctx.Err(); err != nil {
+		return StatusResponse{}, oneerrors.New(oneerrors.Timeout, "Status request was cancelled", oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+	}
+	manifest, err := catalog.LoadEmbedded()
+	if err != nil {
+		return StatusResponse{}, err
+	}
+	options := u.status
+	paths := map[string]string{
+		"env_file": filepath.Join(options.Home, ".oneagent", envFilename(options.Platform.OS)),
+		"profile":  filepath.Join(options.Home, ".oneagent", "profile.json"),
+	}
+	capabilities := Capabilities{
+		CanInstall:        make(map[string]bool, len(manifest.Agents)),
+		MissingRuntime:    make(map[string]string, len(manifest.Agents)),
+		SupportedAgentIDs: make([]string, 0, len(manifest.Agents)),
+	}
+	// Runtime state is read once: it decides both the reported runtime list and
+	// whether a missing package manager is bootstrappable or a hard blocker. Its
+	// resolver is also how Agent commands are found, so a CLI installed into the
+	// managed global prefix reports as installed instead of missing.
+	runtimes, runtimeLookup := u.runtimeCapability(ctx)
+	agentLookup := runtimeLookup.lookup
+	statuses := make(map[string]AgentStatus, len(manifest.Agents))
+	bindings := u.profiles.ListAgentBindings()
+	for _, id := range catalog.AgentIDs(manifest) {
+		agent := manifest.Agents[id]
+		configPath := configPath(options.Home, options.Platform.OS, agent)
+		if configPath != "" {
+			paths[id+"_config"] = configPath
+		}
+		installed := false
+		executable := ""
+		if agent.Command != "" {
+			executable, installed = agentLookup(agent.Command)
+		}
+		canInstall := false
+		if agent.Package != nil {
+			manager := agent.Package.Manager
+			canInstall = runtimeLookup.available(manager)
+			if !canInstall {
+				if runtimeID, bootstrappable := runtimeLookup.provider(manager); bootstrappable {
+					capabilities.MissingRuntime[id] = runtimeID
+				}
+			}
+		}
+		if options.Platform.OS == "windows" {
+			for _, prerequisite := range agent.WindowsPrerequisites {
+				canInstall = canInstall && runtimeLookup.present(prerequisite)
+			}
+		}
+		if contains(agent.Platforms, options.Platform.OS) {
+			capabilities.SupportedAgentIDs = append(capabilities.SupportedAgentIDs, id)
+		}
+		capabilities.CanInstall[id] = canInstall
+		var lockedVersion *string
+		if agent.Package != nil {
+			version := agent.Package.Version
+			lockedVersion = &version
+		}
+		var boundProvider, boundProfileID, boundModel, boundBaseURL, boundUpdatedAt *string
+		if binding, ok := bindings[id]; ok {
+			boundProvider = nonEmptyPointer(binding.Provider)
+			boundProfileID = nonEmptyPointer(binding.ProfileRef)
+			boundModel = nonEmptyPointer(binding.Model)
+			boundBaseURL = nonEmptyPointer(binding.BaseURL)
+			boundUpdatedAt = nonEmptyPointer(binding.UpdatedAt)
+		}
+		var detected *DetectedConfig
+		if agent.ConfigMode == "auto" && configPath != "" {
+			detected = detectedConfig(configReader.DetectFile(configPath, agent.ConfigAdapter, agent.EnvVars))
+		}
+		var installedVersion *string
+		if installed && agent.ConfigMode == "auto" {
+			installedVersion = u.installedVersion(ctx, executable, agent.VersionArgs)
+		}
+		statuses[id] = AgentStatus{
+			Installed:     installed,
+			Configured:    fileExists(configPath),
+			GuideOnly:     agent.ConfigMode == "guide",
+			Config:        configPath,
+			Version:       installedVersion,
+			LockedVersion: lockedVersion,
+			CanInstall:    canInstall,
+			Provider:      boundProvider,
+			ProfileID:     boundProfileID,
+			Model:         boundModel,
+			BaseURL:       boundBaseURL,
+			UpdatedAt:     boundUpdatedAt,
+			Detected:      detected,
+		}
+	}
+	providers, err := u.providers.Public()
+	if err != nil {
+		return StatusResponse{}, err
+	}
+	profiles, activeProfile, environment, environmentError := u.profileStatus(ctx)
+	return StatusResponse{
+		APIVersion:       1,
+		Platform:         options.Platform,
+		Capabilities:     capabilities,
+		Agents:           statuses,
+		Catalog:          catalog.PublicCatalog(manifest, options.Platform.OS),
+		Groups:           catalog.Groups(),
+		Providers:        providers,
+		Mirrors:          catalog.Mirrors(),
+		Paths:            paths,
+		Backups:          backupState(options.Home, options.Platform.OS, manifest),
+		Profiles:         profiles,
+		ActiveProfile:    activeProfile,
+		Runtimes:         runtimes,
+		Environment:      environment,
+		EnvironmentError: environmentError,
+	}, nil
+}
+
+var versionPattern = regexp.MustCompile(`(^|[^\d])(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)`)
+
+// installedVersion mirrors the legacy installed_version(): run the Agent's
+// version command and take the first semver-looking token from either stream.
+// Any failure means "unknown", never an error — status must not break because
+// an Agent's --version is misbehaving.
+func (u *UseCases) installedVersion(ctx context.Context, executable string, versionArgs []string) *string {
+	if executable == "" || u.runner == nil {
+		return nil
+	}
+	args := versionArgs
+	if len(args) == 0 {
+		args = []string{"--version"}
+	}
+	result, err := u.runner.Run(ctx, append([]string{executable}, args...), nil, 30*time.Second)
+	if err != nil {
+		return nil
+	}
+	match := versionPattern.FindStringSubmatch(result.Stdout + "\n" + result.Stderr)
+	if match == nil {
+		return nil
+	}
+	return &match[2]
+}
+
+func detectedConfig(value *configReader.Detected) *DetectedConfig {
+	if value == nil {
+		return nil
+	}
+	return &DetectedConfig{
+		BaseURL:           value.BaseURL,
+		Model:             value.Model,
+		ManagedByOneAgent: value.ManagedByOneAgent,
+		Unreadable:        value.Unreadable,
+	}
+}
+
+func nonEmptyPointer(value string) *string {
+	if value == "" {
+		return nil
+	}
+	return &value
+}
+
+// ListProfiles returns only the public profile projection. Secret files are
+// checked for existence by the profile store, but their contents never enter
+// this use case or its transport DTOs.
+func (u *UseCases) ListProfiles(ctx context.Context) ([]ProfileSummary, error) {
+	if u == nil {
+		return nil, oneerrors.New(oneerrors.InternalError, "Profile service is not configured", oneerrors.WithStatus(501))
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, oneerrors.New(oneerrors.Timeout, "Profile request was cancelled", oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+	}
+	return u.profileSummaries(), nil
+}
+
+// ListAgentBindings returns the public per-Agent routing records used by the
+// CLI's `agent list` command. Binding files contain no credential material.
+func (u *UseCases) ListAgentBindings(ctx context.Context) (map[string]profileStore.AgentBinding, error) {
+	if u == nil {
+		return nil, oneerrors.New(oneerrors.InternalError, "Agent service is not configured", oneerrors.WithStatus(501))
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if err := contextError(ctx, "Agent listing request was cancelled"); err != nil {
+		return nil, err
+	}
+	return u.profiles.ListAgentBindings(), nil
+}
+
+type SaveProfileOptions struct {
+	ID         string
+	Label      string
+	Provider   string
+	APIBaseURL string
+	APIKey     string
+	Model      string
+	ConfigMode string
+	AgentIDs   []string
+}
+
+func (u *UseCases) SaveProfile(ctx context.Context, options SaveProfileOptions) (ProfileSummary, error) {
+	if u == nil {
+		return ProfileSummary{}, oneerrors.New(oneerrors.InternalError, "Profile service is not configured", oneerrors.WithStatus(501))
+	}
+	if err := ctx.Err(); err != nil {
+		return ProfileSummary{}, oneerrors.New(oneerrors.Timeout, "Profile request was cancelled", oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+	}
+	u.writeMu.Lock()
+	defer u.writeMu.Unlock()
+	target, err := u.providers.Resolve(options.Provider, options.APIBaseURL)
+	if err != nil {
+		return ProfileSummary{}, err
+	}
+	if options.APIKey == "" {
+		preserveStoredKey := false
+		for _, item := range u.profiles.List() {
+			if item.ID == options.ID && item.Provider == options.Provider {
+				preserveStoredKey = true
+				break
+			}
+		}
+		if preserveStoredKey {
+			storedKey, readErr := u.profiles.ReadSecret(ctx, options.ID)
+			if readErr != nil {
+				return ProfileSummary{}, readErr
+			}
+			preserveStoredKey = storedKey != ""
+		}
+		if !preserveStoredKey {
+			options.APIKey = target.APIKey
+		}
+	}
+	if options.APIKey != "" {
+		if err := u.providers.SaveKey(ctx, options.Provider, options.APIKey); err != nil {
+			return ProfileSummary{}, err
+		}
+	}
+	stored, err := u.profiles.Save(ctx, profileStore.SaveRequest{
+		ID:         options.ID,
+		Label:      options.Label,
+		Provider:   options.Provider,
+		BaseURL:    target.BaseURL,
+		APIKey:     options.APIKey,
+		Model:      options.Model,
+		ConfigMode: options.ConfigMode,
+		AgentIDs:   append([]string(nil), options.AgentIDs...),
+	})
+	if err != nil {
+		return ProfileSummary{}, err
+	}
+	return profileSummary(stored), nil
+}
+
+func (u *UseCases) profileStatus(ctx context.Context) ([]ProfileSummary, *string, any, *string) {
+	// A v1 read can perform the one-time migration. Serialize that path with
+	// profile writes so the old pointer is backed up before another operation
+	// can publish a new profile state.
+	u.writeMu.Lock()
+	defer u.writeMu.Unlock()
+	active := u.profiles.LoadActiveContext(ctx)
+	// Load the active profile first so the status projection follows the same
+	// read ordering as the legacy implementation when a v1 pointer is present.
+	profiles := u.profileSummaries()
+	var activeID *string
+	if active.ID != "" {
+		id := active.ID
+		activeID = &id
+	}
+	var environment any
+	if active.Environment != nil {
+		environment = active.Environment
+	}
+	var environmentError *string
+	if active.Error != "" {
+		errorText := active.Error
+		environmentError = &errorText
+	}
+	return profiles, activeID, environment, environmentError
+}
+
+func (u *UseCases) profileSummaries() []ProfileSummary {
+	stored := u.profiles.List()
+	result := make([]ProfileSummary, 0, len(stored))
+	for _, item := range stored {
+		result = append(result, profileSummary(item))
+	}
+	return result
+}
+
+func profileSummary(item profileStore.Profile) ProfileSummary {
+	summary := item.Summary()
+	return ProfileSummary{
+		ID:          summary.ID,
+		Label:       summary.Label,
+		Provider:    summary.Provider,
+		BaseURL:     summary.BaseURL,
+		Model:       summary.Model,
+		AgentIDs:    summary.AgentIDs,
+		ActivatedAt: summary.ActivatedAt,
+		HasKey:      summary.HasKey,
+	}
+}
+
+func envFilename(osID string) string {
+	if osID == "windows" {
+		return "env.ps1"
+	}
+	return "env"
+}
+
+func configPath(home, osID string, agent catalog.Agent) string {
+	if agent.ConfigPath == "" {
+		return ""
+	}
+	relative := agent.ConfigPath
+	if osID == "windows" && agent.WindowsConfigPath != "" {
+		relative = agent.WindowsConfigPath
+	}
+	return filepath.Join(home, filepath.FromSlash(relative))
+}
+
+func fileExists(path string) bool {
+	if path == "" {
+		return false
+	}
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+func backupState(home, osID string, manifest catalog.Manifest) map[string]bool {
+	result := make(map[string]bool)
+	for _, id := range catalog.AgentIDs(manifest) {
+		agent := manifest.Agents[id]
+		path := configPath(home, osID, agent)
+		if path == "" {
+			continue
+		}
+		matches, err := filepath.Glob(path + ".backup-*")
+		result[id] = err == nil && len(matches) > 0
+	}
+	envMatches, err := filepath.Glob(filepath.Join(home, ".oneagent", "env.backup-*"))
+	result["env"] = err == nil && len(envMatches) > 0
+	profileMatches, err := filepath.Glob(filepath.Join(home, ".oneagent", "profile.json.backup-*"))
+	result["profile"] = err == nil && len(profileMatches) > 0
+	return result
+}
+
+func contains(values []string, wanted string) bool {
+	for _, value := range values {
+		if strings.EqualFold(value, wanted) {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/app/status_test.go b/internal/app/status_test.go
new file mode 100644
index 00000000..f24fc32f
--- /dev/null
+++ b/internal/app/status_test.go
@@ -0,0 +1,378 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+)
+
+func TestStatusUsesInjectedHomeAndCommandLookup(t *testing.T) {
+	home := t.TempDir()
+	lookup := func(command string) (string, bool) {
+		if command == "npm" || command == "codex" {
+			return "/fake/" + command, true
+		}
+		return "", false
+	}
+	core := NewUseCases(StatusOptions{
+		Home:     home,
+		Platform: platform.For("linux", "amd64"),
+		Lookup:   lookup,
+	})
+	status, err := core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if status.APIVersion != 1 || status.Platform.OS != "linux" {
+		t.Fatalf("unexpected status header: %#v", status)
+	}
+	if !status.Agents["codex"].Installed || !status.Capabilities.CanInstall["codex"] {
+		t.Fatalf("injected command lookup was not used: %#v", status.Agents["codex"])
+	}
+	if status.Paths["profile"] != filepath.Join(home, ".oneagent", "profile.json") {
+		t.Fatalf("profile path escaped injected home: %q", status.Paths["profile"])
+	}
+	wire, err := json.Marshal(status)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(wire) == "" || hasSubstring(string(wire), "api_key") || hasSubstring(string(wire), "fallback") {
+		t.Fatalf("status contains a secret/internal field: %s", wire)
+	}
+}
+
+func TestStatusReportsExistingConfigWithoutWriting(t *testing.T) {
+	home := t.TempDir()
+	path := filepath.Join(home, ".codex", "config.toml")
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte("model = 'local'\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	core := NewUseCases(StatusOptions{Home: home, Platform: platform.For("linux", "amd64"), Lookup: func(string) (string, bool) { return "", false }})
+	status, err := core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !status.Agents["codex"].Configured {
+		t.Fatal("existing config was not observed")
+	}
+}
+
+func TestStatusProjectsProfilesAndActiveEnvironmentWithoutSecrets(t *testing.T) {
+	home := t.TempDir()
+	oneagentDir := filepath.Join(home, ".oneagent")
+	profilesDir := filepath.Join(oneagentDir, "profiles")
+	if err := os.MkdirAll(profilesDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	profileJSON := `{"schema_version":2,"id":"team","label":"Team","provider":"ppio","base_url":"https://api.ppio.com/openai","model":"model-a","config_mode":"provider","agent_ids":["codex","opencode"],"created_at":"created","activated_at":"active","api_key":"must-not-escape"}`
+	if err := os.WriteFile(filepath.Join(profilesDir, "team.json"), []byte(profileJSON), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(oneagentDir, "secrets"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(oneagentDir, "secrets", "team.env"), []byte("export ONEAGENT_API_KEY=sk-secret\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(oneagentDir, "profile.json"), []byte(`{"schema_version":2,"active":"team"}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	core := NewUseCases(StatusOptions{
+		Home:     home,
+		Platform: platform.For("linux", "amd64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	})
+	status, err := core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(status.Profiles) != 1 || status.Profiles[0].ID != "team" || !status.Profiles[0].HasKey {
+		t.Fatalf("profile summaries = %#v", status.Profiles)
+	}
+	if status.ActiveProfile == nil || *status.ActiveProfile != "team" {
+		t.Fatalf("active profile = %#v", status.ActiveProfile)
+	}
+	environment, ok := status.Environment.(map[string]any)
+	if !ok || environment["provider"] != "ppio" || environment["model"] != "model-a" {
+		t.Fatalf("environment projection = %#v", status.Environment)
+	}
+	if _, leaked := environment["api_key"]; leaked {
+		t.Fatalf("environment exposed a secret: %#v", environment)
+	}
+	wire, err := json.Marshal(status)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(wire), "sk-secret") || strings.Contains(string(wire), "must-not-escape") {
+		t.Fatalf("status contains secret material: %s", wire)
+	}
+}
+
+func TestStatusKeepsLegacyProfileInMemoryAndReportsFailures(t *testing.T) {
+	home := t.TempDir()
+	oneagentDir := filepath.Join(home, ".oneagent")
+	if err := os.MkdirAll(oneagentDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	legacy := `{"schema_version":1,"provider":"ppio","base_url":"https://api.ppio.com/openai","model":"legacy-model","config_mode":"provider","agent_ids":["codex"],"activated_at":"legacy-time"}`
+	if err := os.WriteFile(filepath.Join(oneagentDir, "profile.json"), []byte(legacy), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	core := NewUseCases(StatusOptions{Home: home, Platform: platform.For("linux", "amd64"), Lookup: func(string) (string, bool) { return "", false }})
+	status, err := core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if status.ActiveProfile == nil || *status.ActiveProfile != "default" || status.Environment == nil || status.EnvironmentError != nil || len(status.Profiles) != 1 || status.Profiles[0].ID != "default" {
+		t.Fatalf("legacy status = %#v", status)
+	}
+
+	if err := os.WriteFile(filepath.Join(oneagentDir, "profile.json"), []byte(`{"schema_version":2,"active":"ghost"}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	status, err = core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if status.ActiveProfile == nil || *status.ActiveProfile != "ghost" || status.Environment != nil || status.EnvironmentError == nil || !strings.Contains(*status.EnvironmentError, "ghost") {
+		t.Fatalf("missing profile status = %#v", status)
+	}
+
+	if err := os.MkdirAll(filepath.Join(oneagentDir, "profiles"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(oneagentDir, "profiles", "ghost.json"), []byte("{"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	status, err = core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if status.EnvironmentError == nil || status.Environment != nil {
+		t.Fatalf("corrupt profile status = %#v", status)
+	}
+}
+
+func TestSaveProfileUseCaseWritesOnlyPublicSummary(t *testing.T) {
+	home := t.TempDir()
+	core := NewUseCases(StatusOptions{
+		Home:     home,
+		Platform: platform.For("linux", "amd64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	})
+	summary, err := core.SaveProfile(context.Background(), SaveProfileOptions{
+		ID:         "team",
+		Label:      "Team",
+		Provider:   "ppio",
+		Model:      "model-a",
+		APIKey:     "sk-secret",
+		ConfigMode: "provider",
+		AgentIDs:   []string{"opencode", "codex"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if summary.ID != "team" || !summary.HasKey || !reflect.DeepEqual(summary.AgentIDs, []string{"codex", "opencode"}) {
+		t.Fatalf("saved summary = %#v", summary)
+	}
+	if err := core.providers.SaveKey(context.Background(), "ppio", "new-provider-key"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := core.SaveProfile(context.Background(), SaveProfileOptions{
+		ID: "team", Label: "Renamed", Provider: "ppio", Model: "model-b", AgentIDs: []string{"codex"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if key, err := core.profiles.ReadSecret(context.Background(), "team"); err != nil || key != "sk-secret" {
+		t.Fatalf("blank profile edit replaced its saved key: %q, %v", key, err)
+	}
+	status, err := core.GetStatus(context.Background())
+	if err != nil || len(status.Profiles) != 1 || status.Profiles[0].ID != "team" {
+		t.Fatalf("status after save = %#v, err=%v", status, err)
+	}
+	wire, err := json.Marshal(summary)
+	if err != nil || strings.Contains(string(wire), "sk-secret") || strings.Contains(string(wire), "api_key") {
+		t.Fatalf("summary leaked secret data: %s (%v)", wire, err)
+	}
+}
+
+func TestStatusProjectsAgentBindingsWithoutUnknownFields(t *testing.T) {
+	home := t.TempDir()
+	path := filepath.Join(home, ".oneagent", "agents", "codex.json")
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	content := `{"schema_version":1,"agent_id":"codex","provider":"ppio","base_url":"https://api.ppio.com/responses","model":"model-a","profile_ref":"team","created_at":"created","updated_at":"updated","api_key":"must-not-escape"}`
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	core := NewUseCases(StatusOptions{Home: home, Platform: platform.For("linux", "amd64"), Lookup: func(string) (string, bool) { return "", false }})
+	status, err := core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	agent := status.Agents["codex"]
+	if agent.Provider == nil || *agent.Provider != "ppio" || agent.ProfileID == nil || *agent.ProfileID != "team" || agent.Model == nil || *agent.Model != "model-a" || agent.BaseURL == nil || *agent.BaseURL != "https://api.ppio.com/responses" || agent.UpdatedAt == nil || *agent.UpdatedAt != "updated" {
+		t.Fatalf("agent binding projection = %#v", agent)
+	}
+	wire, err := json.Marshal(status)
+	if err != nil || strings.Contains(string(wire), "must-not-escape") || strings.Contains(string(wire), "api_key") {
+		t.Fatalf("status binding leaked unknown fields: %s (%v)", wire, err)
+	}
+}
+
+func TestStatusDetectsExternalConfigWithoutSecretsOrGlobalFailure(t *testing.T) {
+	home := t.TempDir()
+	codexPath := filepath.Join(home, ".codex", "config.toml")
+	claudePath := filepath.Join(home, ".claude", "settings.json")
+	if err := os.MkdirAll(filepath.Dir(codexPath), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Dir(claudePath), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(codexPath, []byte(`model_provider = "vendor"
+model = "gpt-5-mini"
+[model_providers.vendor]
+base_url = "https://api.other-vendor.com/v1"
+api_key = "sk-detected-secret"
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(claudePath, []byte("{not json"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	core := NewUseCases(StatusOptions{Home: home, Platform: platform.For("linux", "amd64"), Lookup: func(string) (string, bool) { return "", false }})
+	status, err := core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	codex := status.Agents["codex"]
+	if codex.Detected == nil || codex.Detected.BaseURL != "https://api.other-vendor.com/v1" || codex.Detected.Model != "gpt-5-mini" || codex.Detected.ManagedByOneAgent {
+		t.Fatalf("codex detected = %#v", codex.Detected)
+	}
+	claude := status.Agents["claude-code"]
+	if claude.Detected == nil || claude.Detected.Unreadable == nil {
+		t.Fatalf("claude malformed detection = %#v", claude.Detected)
+	}
+	wire, err := json.Marshal(status)
+	if err != nil || strings.Contains(string(wire), "sk-detected-secret") || strings.Contains(string(wire), "api_key") {
+		t.Fatalf("detected status leaked secret data: %s (%v)", wire, err)
+	}
+	if status.Agents["openclaw"].Detected != nil {
+		t.Fatalf("guide-only Agent unexpectedly detected config: %#v", status.Agents["openclaw"].Detected)
+	}
+}
+
+func TestStatusReportsInstalledVersionFromVersionCommand(t *testing.T) {
+	home := t.TempDir()
+	runner := &installAppRunner{paths: map[string]string{"codex": "/fake/codex"}}
+	core := NewUseCases(StatusOptions{
+		Home:     home,
+		Platform: platform.For("linux", "amd64"),
+		Runner:   runner,
+	})
+	status, err := core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	codex := status.Agents["codex"]
+	if !codex.Installed || codex.Version == nil || *codex.Version != "1.0.0" {
+		t.Fatalf("installed version not detected: %#v", codex)
+	}
+	found := false
+	for _, call := range runner.calls {
+		if reflect.DeepEqual(call, []string{"/fake/codex", "--version"}) {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("version command was not invoked: %#v", runner.calls)
+	}
+	if openclaw := status.Agents["openclaw"]; openclaw.Version != nil {
+		t.Fatalf("guide-only Agent should not report a version: %#v", openclaw)
+	}
+}
+
+func TestStatusMatchesEmptyLinuxARM64Fixture(t *testing.T) {
+	home := t.TempDir()
+	core := NewUseCases(StatusOptions{
+		Home:     home,
+		Platform: platform.For("linux", "arm64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	})
+	status, err := core.GetStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	actualData, err := json.Marshal(status)
+	if err != nil {
+		t.Fatal(err)
+	}
+	fixtureData, err := os.ReadFile(filepath.Join("testdata", "status-empty-linux-arm64.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var actual any
+	var expected any
+	if err := json.Unmarshal(actualData, &actual); err != nil {
+		t.Fatal(err)
+	}
+	if err := json.Unmarshal(fixtureData, &expected); err != nil {
+		t.Fatal(err)
+	}
+	actual = normalizeFixtureHome(actual, home)
+	if !reflect.DeepEqual(actual, expected) {
+		actualPretty, _ := json.MarshalIndent(actual, "", "  ")
+		expectedPretty, _ := json.MarshalIndent(expected, "", "  ")
+		t.Fatalf("status diverged from the frozen fixture\nwant:\n%s\ngot:\n%s", expectedPretty, actualPretty)
+	}
+}
+
+func TestStatusHonorsCancellation(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err := NewUseCases(StatusOptions{Platform: platform.For("linux", "amd64")}).GetStatus(ctx)
+	if err == nil || !hasSubstring(err.Error(), "cancelled") {
+		t.Fatalf("cancellation was not mapped: %v", err)
+	}
+}
+
+func hasSubstring(value, needle string) bool {
+	for index := 0; index+len(needle) <= len(value); index++ {
+		if value[index:index+len(needle)] == needle {
+			return true
+		}
+	}
+	return false
+}
+
+func normalizeFixtureHome(value any, home string) any {
+	switch item := value.(type) {
+	case string:
+		normalized := strings.ReplaceAll(item, home, "${HOME}")
+		if strings.HasPrefix(normalized, "${HOME}") {
+			return filepath.ToSlash(normalized)
+		}
+		return normalized
+	case []any:
+		for index := range item {
+			item[index] = normalizeFixtureHome(item[index], home)
+		}
+	case map[string]any:
+		for key := range item {
+			item[key] = normalizeFixtureHome(item[key], home)
+		}
+	}
+	return value
+}
diff --git a/internal/app/testdata/status-empty-linux-arm64.json b/internal/app/testdata/status-empty-linux-arm64.json
new file mode 100644
index 00000000..dd55bdce
--- /dev/null
+++ b/internal/app/testdata/status-empty-linux-arm64.json
@@ -0,0 +1,591 @@
+{
+  "apiVersion": 1,
+  "platform": {
+    "os": "linux",
+    "arch": "arm64",
+    "shell": "bash"
+  },
+  "capabilities": {
+    "canInstall": {
+      "codex": false,
+      "claude-code": false,
+      "opencode": false,
+      "kilo-cli": false,
+      "aider": false,
+      "openclaw": false,
+      "hermes": false,
+      "cursor": false,
+      "kiro": false,
+      "gemini-cli": false,
+      "cline": false,
+      "continue": false,
+      "qwen-code": false,
+      "kilo-vscode": false
+    },
+    "supportedAgentIds": [
+      "codex",
+      "claude-code",
+      "opencode",
+      "kilo-cli",
+      "aider",
+      "openclaw",
+      "hermes",
+      "cursor",
+      "kiro",
+      "gemini-cli",
+      "cline",
+      "continue",
+      "qwen-code",
+      "kilo-vscode"
+    ],
+    "missingRuntime": {
+      "aider": "uv",
+      "claude-code": "node",
+      "codex": "node",
+      "kilo-cli": "node",
+      "opencode": "node"
+    }
+  },
+  "agents": {
+    "codex": {
+      "installed": false,
+      "config": "${HOME}/.codex/config.toml",
+      "configured": false,
+      "guideOnly": false,
+      "version": null,
+      "lockedVersion": "0.145.0",
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "claude-code": {
+      "installed": false,
+      "config": "${HOME}/.claude/settings.json",
+      "configured": false,
+      "guideOnly": false,
+      "version": null,
+      "lockedVersion": "2.1.217",
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "opencode": {
+      "installed": false,
+      "config": "${HOME}/.config/opencode/opencode.jsonc",
+      "configured": false,
+      "guideOnly": false,
+      "version": null,
+      "lockedVersion": "1.18.4",
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "kilo-cli": {
+      "installed": false,
+      "config": "${HOME}/.config/kilo/kilo.jsonc",
+      "configured": false,
+      "guideOnly": false,
+      "version": null,
+      "lockedVersion": "7.4.11",
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "aider": {
+      "installed": false,
+      "config": "${HOME}/.oneagent/aider.env",
+      "configured": false,
+      "guideOnly": false,
+      "version": null,
+      "lockedVersion": "0.86.2",
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "openclaw": {
+      "installed": false,
+      "config": "",
+      "configured": false,
+      "guideOnly": true,
+      "version": null,
+      "lockedVersion": null,
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "hermes": {
+      "installed": false,
+      "config": "",
+      "configured": false,
+      "guideOnly": true,
+      "version": null,
+      "lockedVersion": null,
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "cursor": {
+      "installed": false,
+      "config": "",
+      "configured": false,
+      "guideOnly": true,
+      "version": null,
+      "lockedVersion": null,
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "kiro": {
+      "installed": false,
+      "config": "",
+      "configured": false,
+      "guideOnly": true,
+      "version": null,
+      "lockedVersion": null,
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "gemini-cli": {
+      "installed": false,
+      "config": "",
+      "configured": false,
+      "guideOnly": true,
+      "version": null,
+      "lockedVersion": null,
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "cline": {
+      "installed": false,
+      "config": "",
+      "configured": false,
+      "guideOnly": true,
+      "version": null,
+      "lockedVersion": null,
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "continue": {
+      "installed": false,
+      "config": "",
+      "configured": false,
+      "guideOnly": true,
+      "version": null,
+      "lockedVersion": null,
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "qwen-code": {
+      "installed": false,
+      "config": "",
+      "configured": false,
+      "guideOnly": true,
+      "version": null,
+      "lockedVersion": null,
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    },
+    "kilo-vscode": {
+      "installed": false,
+      "config": "",
+      "configured": false,
+      "guideOnly": true,
+      "version": null,
+      "lockedVersion": null,
+      "canInstall": false,
+      "provider": null,
+      "model": null,
+      "baseUrl": null,
+      "updatedAt": null,
+      "detected": null,
+      "profileId": null
+    }
+  },
+  "catalog": [
+    {
+      "id": "codex",
+      "name": "Codex",
+      "group": "auto",
+      "configMode": "auto",
+      "guideOnly": false,
+      "lockedVersion": "0.145.0",
+      "protocol": "responses",
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 1
+    },
+    {
+      "id": "claude-code",
+      "name": "Claude Code",
+      "group": "auto",
+      "configMode": "auto",
+      "guideOnly": false,
+      "lockedVersion": "2.1.217",
+      "protocol": "anthropic",
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 2
+    },
+    {
+      "id": "cursor",
+      "name": "Cursor",
+      "group": "platform",
+      "configMode": "guide",
+      "guideOnly": true,
+      "lockedVersion": null,
+      "protocol": null,
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 3
+    },
+    {
+      "id": "opencode",
+      "name": "OpenCode",
+      "group": "auto",
+      "configMode": "auto",
+      "guideOnly": false,
+      "lockedVersion": "1.18.4",
+      "protocol": "openai",
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 4
+    },
+    {
+      "id": "openclaw",
+      "name": "OpenClaw",
+      "group": "gateway",
+      "configMode": "guide",
+      "guideOnly": true,
+      "lockedVersion": null,
+      "protocol": null,
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 5
+    },
+    {
+      "id": "hermes",
+      "name": "Hermes",
+      "group": "gateway",
+      "configMode": "guide",
+      "guideOnly": true,
+      "lockedVersion": null,
+      "protocol": null,
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 6
+    },
+    {
+      "id": "gemini-cli",
+      "name": "Gemini CLI",
+      "group": "platform",
+      "configMode": "guide",
+      "guideOnly": true,
+      "lockedVersion": null,
+      "protocol": null,
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 7
+    },
+    {
+      "id": "kilo-cli",
+      "name": "Kilo CLI",
+      "group": "auto",
+      "configMode": "auto",
+      "guideOnly": false,
+      "lockedVersion": "7.4.11",
+      "protocol": "openai",
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 8
+    },
+    {
+      "id": "aider",
+      "name": "Aider",
+      "group": "auto",
+      "configMode": "auto",
+      "guideOnly": false,
+      "lockedVersion": "0.86.2",
+      "protocol": "openai",
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 9
+    },
+    {
+      "id": "kiro",
+      "name": "Kiro",
+      "group": "platform",
+      "configMode": "guide",
+      "guideOnly": true,
+      "lockedVersion": null,
+      "protocol": null,
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 10
+    },
+    {
+      "id": "cline",
+      "name": "Cline",
+      "group": "ide",
+      "configMode": "guide",
+      "guideOnly": true,
+      "lockedVersion": null,
+      "protocol": null,
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 11
+    },
+    {
+      "id": "continue",
+      "name": "Continue",
+      "group": "ide",
+      "configMode": "guide",
+      "guideOnly": true,
+      "lockedVersion": null,
+      "protocol": null,
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 12
+    },
+    {
+      "id": "qwen-code",
+      "name": "Qwen Code",
+      "group": "ide",
+      "configMode": "guide",
+      "guideOnly": true,
+      "lockedVersion": null,
+      "protocol": null,
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 13
+    },
+    {
+      "id": "kilo-vscode",
+      "name": "Kilo VS Code",
+      "group": "ide",
+      "configMode": "guide",
+      "guideOnly": true,
+      "lockedVersion": null,
+      "protocol": null,
+      "platforms": [
+        "macos",
+        "linux",
+        "windows"
+      ],
+      "platformNote": "",
+      "rank": 14
+    }
+  ],
+  "groups": [
+    {
+      "id": "auto",
+      "name": "One-click configurable"
+    },
+    {
+      "id": "gateway",
+      "name": "Gateway agents"
+    },
+    {
+      "id": "platform",
+      "name": "Official account agents"
+    },
+    {
+      "id": "ide",
+      "name": "IDE extensions"
+    }
+  ],
+  "providers": {
+    "ppio": {
+      "name": "PPIO",
+      "home": "https://ppio.com/",
+      "base_url": "https://api.ppio.com/openai",
+      "anthropic_base_url": "https://api.ppio.com/anthropic"
+    },
+    "novita": {
+      "name": "Novita",
+      "home": "https://novita.ai/",
+      "base_url": "https://api.novita.ai/openai",
+      "anthropic_base_url": "https://api.novita.ai/anthropic"
+    }
+  },
+  "mirrors": [
+    {
+      "id": "official",
+      "name": "官方源",
+      "registry": "https://registry.npmjs.org/",
+      "upstream": "https://registry.npmjs.org/",
+      "note": "npm 官方 registry，默认使用。"
+    },
+    {
+      "id": "npmmirror",
+      "name": "npmmirror（阿里云）",
+      "registry": "https://registry.npmmirror.com/",
+      "upstream": "https://registry.npmjs.org/",
+      "note": "官方源的公开只读镜像，包体与校验值均与官方一致；官方源不可达时可用。"
+    }
+  ],
+  "paths": {
+    "env_file": "${HOME}/.oneagent/env",
+    "profile": "${HOME}/.oneagent/profile.json",
+    "codex_config": "${HOME}/.codex/config.toml",
+    "claude-code_config": "${HOME}/.claude/settings.json",
+    "opencode_config": "${HOME}/.config/opencode/opencode.jsonc",
+    "kilo-cli_config": "${HOME}/.config/kilo/kilo.jsonc",
+    "aider_config": "${HOME}/.oneagent/aider.env"
+  },
+  "backups": {
+    "codex": false,
+    "claude-code": false,
+    "opencode": false,
+    "kilo-cli": false,
+    "aider": false,
+    "env": false,
+    "profile": false
+  },
+  "profiles": [],
+  "activeProfile": null,
+  "environment": null,
+  "environmentError": null,
+  "runtimes": [
+    {
+      "id": "node",
+      "name": "Node.js",
+      "command": "npm",
+      "installed": false,
+      "version": "",
+      "lockedVersion": "24.18.1",
+      "managed": false,
+      "supported": true,
+      "note": "",
+      "license": "MIT",
+      "licenseUrl": "https://github.com/nodejs/node/blob/main/LICENSE",
+      "source": "https://nodejs.org/dist/",
+      "installPath": "${HOME}/.oneagent/runtimes/node/v24.18.1",
+      "requiredByHint": "Codex, Claude Code, OpenCode +1"
+    },
+    {
+      "id": "uv",
+      "name": "uv",
+      "command": "uv",
+      "installed": false,
+      "version": "",
+      "lockedVersion": "0.12.1",
+      "managed": false,
+      "supported": true,
+      "note": "uv manages its own CPython download for Aider; OneAgent does not fetch Python directly.",
+      "license": "MIT OR Apache-2.0",
+      "licenseUrl": "https://github.com/astral-sh/uv/blob/main/LICENSE-APACHE",
+      "source": "https://github.com/astral-sh/uv/releases",
+      "installPath": "${HOME}/.oneagent/runtimes/uv/v0.12.1",
+      "requiredByHint": "Aider"
+    }
+  ]
+}
diff --git a/internal/binding/services.go b/internal/binding/services.go
new file mode 100644
index 00000000..ca85bc22
--- /dev/null
+++ b/internal/binding/services.go
@@ -0,0 +1,553 @@
+// Package binding contains transport DTOs and the narrow Wails-facing service
+// layer. Business logic belongs in internal/app and is not duplicated here.
+package binding
+
+import (
+	"context"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/app"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+)
+
+type Services struct {
+	Status   *StatusService
+	Provider *ProviderService
+	Agent    *AgentService
+	Profile  *ProfileService
+	Runtime  *RuntimeService
+}
+
+type ServicesOptions struct {
+	AfterGetStatus func()
+	InstallOutput  process.OutputListener
+}
+
+func NewServices(core *app.UseCases, opener BrowserOpener) *Services {
+	return NewServicesWithOptions(core, opener, ServicesOptions{})
+}
+
+func NewServicesWithOptions(core *app.UseCases, opener BrowserOpener, options ServicesOptions) *Services {
+	return &Services{
+		Status:   &StatusService{core: core, afterGetStatus: options.AfterGetStatus},
+		Provider: NewProviderService(core, opener),
+		Agent:    &AgentService{core: core, onOutput: options.InstallOutput},
+		Profile:  NewProfileService(core),
+		Runtime:  &RuntimeService{core: core, onOutput: options.InstallOutput},
+	}
+}
+
+// RuntimeService exposes the Node.js and uv bootstrap. It reuses the install
+// output listener so the UI shows runtime downloads in the same log pane as
+// Agent installs.
+type RuntimeService struct {
+	core     *app.UseCases
+	onOutput process.OutputListener
+}
+
+func NewRuntimeService(core *app.UseCases) *RuntimeService {
+	return &RuntimeService{core: core}
+}
+
+func (s *RuntimeService) ListRuntimes(ctx context.Context) ([]app.RuntimeStatus, error) {
+	if err := contextError(ctx); err != nil {
+		return nil, err
+	}
+	if s == nil || s.core == nil {
+		return nil, notReady("Runtime service is not configured")
+	}
+	return s.core.RuntimeStatuses(ctx)
+}
+
+func (s *RuntimeService) InstallRuntime(ctx context.Context, request InstallRuntimeRequest) (app.InstallRuntimeResult, error) {
+	if err := contextError(ctx); err != nil {
+		return app.InstallRuntimeResult{}, err
+	}
+	if s == nil || s.core == nil {
+		return app.InstallRuntimeResult{}, notReady("Runtime service is not configured")
+	}
+	if strings.TrimSpace(request.Runtime) == "" {
+		return app.InstallRuntimeResult{}, oneerrors.New(oneerrors.InvalidRequest, "runtime is required")
+	}
+	return s.core.InstallRuntime(ctx, app.InstallRuntimeOptions{
+		RuntimeID: strings.TrimSpace(request.Runtime),
+		Output:    s.onOutput,
+	})
+}
+
+type StatusService struct {
+	core           *app.UseCases
+	afterGetStatus func()
+}
+
+func (s *StatusService) GetStatus(ctx context.Context) (app.StatusResponse, error) {
+	if s == nil || s.core == nil {
+		return app.StatusResponse{}, notReady("Status service is not configured")
+	}
+	status, err := s.core.GetStatus(ctx)
+	if err == nil && s.afterGetStatus != nil {
+		s.afterGetStatus()
+	}
+	return status, err
+}
+
+type BrowserOpener func(string) error
+
+type ProviderService struct {
+	opener BrowserOpener
+	core   *app.UseCases
+}
+
+func NewProviderService(core *app.UseCases, opener BrowserOpener) *ProviderService {
+	return &ProviderService{opener: opener, core: core}
+}
+
+func (s *ProviderService) Probe(ctx context.Context, request ProbeRequest) (ProbeResponse, error) {
+	if err := contextError(ctx); err != nil {
+		return ProbeResponse{}, err
+	}
+	if s == nil || s.core == nil {
+		return ProbeResponse{}, notReady("Provider probing is not configured")
+	}
+	result, err := s.core.ProbeProvider(ctx, app.ProviderProbeOptions{
+		Provider:   request.Provider,
+		APIBaseURL: request.APIBaseURL,
+		APIKey:     request.APIKey,
+		Model:      request.Model,
+		AgentIDs:   request.Agents,
+	})
+	if err != nil {
+		return ProbeResponse{}, err
+	}
+	response := probeResponse(result.Primary)
+	response.Protocols = make(map[string]ProbeResponse, len(result.Protocols))
+	for protocolID, protocolResult := range result.Protocols {
+		response.Protocols[protocolID] = probeResponse(protocolResult)
+	}
+	return response, nil
+}
+
+func (s *ProviderService) ListModels(ctx context.Context, request ModelsRequest) (ModelsResponse, error) {
+	if err := contextError(ctx); err != nil {
+		return ModelsResponse{}, err
+	}
+	if s == nil || s.core == nil {
+		return ModelsResponse{}, notReady("Model discovery is not configured")
+	}
+	result, err := s.core.ListProviderModels(ctx, request.Provider, request.APIKey, request.APIBaseURL)
+	if err != nil {
+		return ModelsResponse{}, err
+	}
+	return modelsResponse(result), nil
+}
+
+func (s *ProviderService) GetProvider(ctx context.Context, request ProviderIDRequest) (provider.Entry, error) {
+	if err := contextError(ctx); err != nil {
+		return provider.Entry{}, err
+	}
+	if s == nil || s.core == nil {
+		return provider.Entry{}, notReady("Provider service is not configured")
+	}
+	return s.core.GetProvider(ctx, request.ID)
+}
+
+func (s *ProviderService) SaveProvider(ctx context.Context, request SaveProviderRequest) (provider.Entry, error) {
+	if err := contextError(ctx); err != nil {
+		return provider.Entry{}, err
+	}
+	if s == nil || s.core == nil {
+		return provider.Entry{}, notReady("Provider service is not configured")
+	}
+	return s.core.SaveProvider(ctx, provider.Entry{
+		ID: request.ID, Name: request.Name, Home: request.Home,
+		BaseURL: request.BaseURL, AnthropicBaseURL: request.AnthropicBaseURL, APIKey: request.APIKey,
+	})
+}
+
+func (s *ProviderService) DeleteProvider(ctx context.Context, request ProviderIDRequest) (ProviderMutationResponse, error) {
+	if err := contextError(ctx); err != nil {
+		return ProviderMutationResponse{}, err
+	}
+	if s == nil || s.core == nil {
+		return ProviderMutationResponse{}, notReady("Provider service is not configured")
+	}
+	if err := s.core.DeleteProvider(ctx, request.ID); err != nil {
+		return ProviderMutationResponse{}, err
+	}
+	return ProviderMutationResponse{OK: true}, nil
+}
+
+func (s *ProviderService) OpenRegistration(ctx context.Context, request OpenRegistrationRequest) (OpenRegistrationResponse, error) {
+	if err := contextError(ctx); err != nil {
+		return OpenRegistrationResponse{}, err
+	}
+	if s == nil || s.core == nil {
+		return OpenRegistrationResponse{}, notReady("Provider service is not configured")
+	}
+	entry, err := s.core.GetProvider(ctx, request.Provider)
+	if err != nil || entry.Home == "" {
+		return OpenRegistrationResponse{}, oneerrors.New(oneerrors.InvalidRequest, "Registration is only available for a Provider with a home URL")
+	}
+	parsed, err := url.Parse(entry.Home)
+	if err != nil || parsed.User != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.Host == "" {
+		return OpenRegistrationResponse{}, oneerrors.New(oneerrors.InvalidRequest, "Provider registration URL is invalid")
+	}
+	if s == nil || s.opener == nil {
+		return OpenRegistrationResponse{OK: true, URL: entry.Home, Message: "Provider registration URL validated"}, nil
+	}
+	if err := s.opener(entry.Home); err != nil {
+		return OpenRegistrationResponse{}, oneerrors.New(oneerrors.InternalError, "Unable to open Provider registration", oneerrors.WithStatus(500), oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+	}
+	return OpenRegistrationResponse{OK: true, URL: entry.Home, Message: "Provider registration opened"}, nil
+}
+
+type AgentService struct {
+	core     *app.UseCases
+	onOutput process.OutputListener
+}
+
+func NewAgentService(core *app.UseCases) *AgentService {
+	return &AgentService{core: core}
+}
+
+func (s *AgentService) Install(ctx context.Context, request InstallRequest) (InstallResponse, error) {
+	if err := contextError(ctx); err != nil {
+		return InstallResponse{}, err
+	}
+	if s == nil || s.core == nil {
+		return InstallResponse{}, notReady("Agent installation is not configured")
+	}
+	timeout := 180 * time.Second
+	if request.Timeout < 0 || request.Timeout > 3600 {
+		return InstallResponse{}, oneerrors.New(oneerrors.InvalidRequest, "timeout must be an integer between 1 and 3600")
+	}
+	if request.Timeout > 0 {
+		timeout = time.Duration(request.Timeout) * time.Second
+	}
+	result, err := s.core.InstallAgents(ctx, app.InstallAgentsOptions{
+		Agents:         append([]string(nil), request.Agents...),
+		ProfileAgents:  append([]string(nil), request.ProfileAgents...),
+		Provider:       request.Provider,
+		APIBaseURL:     request.APIBaseURL,
+		APIKey:         request.APIKey,
+		Model:          request.Model,
+		SmallFastModel: request.SmallFastModel,
+		ProfileID:      request.ProfileID,
+		Configure:      request.Configure,
+		InstallAgent:   request.InstallAgent,
+		CheckAgentOnly: false,
+		SkipTest:       request.SkipTest,
+		LockedVersion:  request.LockedVersion,
+		Latest:         request.Latest,
+		Timeout:        timeout,
+		Registry:       request.Registry,
+		Output:         s.onOutput,
+	})
+	if err != nil {
+		return InstallResponse{}, err
+	}
+	return installResponse(result), nil
+}
+
+func (s *AgentService) Activate(ctx context.Context, request ActivateRequest) (ActivateResponse, error) {
+	if err := contextError(ctx); err != nil {
+		return ActivateResponse{}, err
+	}
+	if s == nil || s.core == nil {
+		return ActivateResponse{}, notReady("Agent activation is not configured")
+	}
+	result, err := s.core.ActivateAgent(ctx, app.ActivateAgentOptions{
+		AgentID:        request.AgentID,
+		Provider:       request.Provider,
+		APIBaseURL:     request.APIBaseURL,
+		APIKey:         request.APIKey,
+		Model:          request.Model,
+		ProfileID:      request.ProfileID,
+		SmallFastModel: request.SmallFastModel,
+	})
+	if err != nil {
+		return ActivateResponse{}, err
+	}
+	return ActivateResponse{
+		OK:       true,
+		Agent:    result.AgentID,
+		Config:   result.Config,
+		Provider: result.Provider,
+		Model:    result.Model,
+		Restart:  result.Restart,
+		Next:     result.Next,
+	}, nil
+}
+
+type ProfileService struct {
+	core *app.UseCases
+}
+
+func NewProfileService(core *app.UseCases) *ProfileService {
+	return &ProfileService{core: core}
+}
+
+func (s *ProfileService) ListProfiles(ctx context.Context) ([]app.ProfileSummary, error) {
+	if err := contextError(ctx); err != nil {
+		return nil, err
+	}
+	if s == nil || s.core == nil {
+		return nil, notReady("Profile listing is not configured")
+	}
+	return s.core.ListProfiles(ctx)
+}
+
+func (s *ProfileService) SaveProfile(ctx context.Context, request SaveProfileRequest) (app.ProfileSummary, error) {
+	if err := contextError(ctx); err != nil {
+		return app.ProfileSummary{}, err
+	}
+	if s == nil || s.core == nil {
+		return app.ProfileSummary{}, notReady("Profile service is not configured")
+	}
+	return s.core.SaveProfile(ctx, app.SaveProfileOptions{
+		ID:         request.ID,
+		Label:      request.Label,
+		Provider:   request.Provider,
+		APIBaseURL: request.APIBaseURL,
+		APIKey:     request.APIKey,
+		Model:      request.Model,
+		ConfigMode: request.ConfigMode,
+		AgentIDs:   append([]string(nil), request.AgentIDs...),
+	})
+}
+
+type ProbeRequest struct {
+	Provider   string   `json:"provider"`
+	APIBaseURL string   `json:"api_base_url"`
+	APIKey     string   `json:"api_key"`
+	Model      string   `json:"model"`
+	Agents     []string `json:"agents"`
+}
+
+type ModelsRequest struct {
+	Provider   string `json:"provider"`
+	APIBaseURL string `json:"api_base_url"`
+	APIKey     string `json:"api_key"`
+}
+
+type OpenRegistrationRequest struct {
+	Provider string   `json:"provider"`
+	Agents   []string `json:"agents"`
+}
+
+type ProviderIDRequest struct {
+	ID string `json:"id"`
+}
+
+type InstallRuntimeRequest struct {
+	Runtime string `json:"runtime"`
+}
+
+type SaveProviderRequest struct {
+	ID               string `json:"id"`
+	Name             string `json:"name"`
+	Home             string `json:"home"`
+	BaseURL          string `json:"base_url"`
+	AnthropicBaseURL string `json:"anthropic_base_url"`
+	APIKey           string `json:"api_key"`
+}
+
+type ProviderMutationResponse struct {
+	OK bool `json:"ok"`
+}
+
+type OpenRegistrationResponse struct {
+	OK      bool   `json:"ok"`
+	URL     string `json:"url"`
+	Message string `json:"message"`
+}
+
+type ProbeResponse struct {
+	OK        bool                     `json:"ok"`
+	Reachable bool                     `json:"reachable"`
+	Status    int                      `json:"status"`
+	Message   string                   `json:"message"`
+	ErrorCode *string                  `json:"error_code"`
+	Retryable bool                     `json:"retryable"`
+	Protocol  *string                  `json:"protocol,omitempty"`
+	Protocols map[string]ProbeResponse `json:"protocols,omitempty"`
+}
+
+type ModelsResponse struct {
+	ProbeResponse
+	Models []string `json:"models"`
+}
+
+type InstallRequest struct {
+	Agents         []string `json:"agents"`
+	ProfileAgents  []string `json:"profile_agents"`
+	Provider       string   `json:"provider"`
+	APIBaseURL     string   `json:"api_base_url"`
+	APIKey         string   `json:"api_key"`
+	Model          string   `json:"model"`
+	SmallFastModel string   `json:"small_fast_model"`
+	ProfileID      string   `json:"profile_id"`
+	Configure      bool     `json:"configure"`
+	InstallAgent   bool     `json:"install_agent"`
+	LockedVersion  bool     `json:"locked_version"`
+	Latest         bool     `json:"latest"`
+	SkipTest       bool     `json:"skip_test"`
+	Registry       string   `json:"registry"`
+	Timeout        int      `json:"timeout"`
+}
+
+type AgentInstallResult struct {
+	Agent         string   `json:"agent"`
+	Status        string   `json:"status"`
+	Config        *string  `json:"config,omitempty"`
+	Installed     *bool    `json:"installed,omitempty"`
+	Version       **string `json:"version,omitempty"`
+	LockedVersion **string `json:"lockedVersion,omitempty"`
+	Registry      *string  `json:"registry,omitempty"`
+	Code          *int     `json:"code,omitempty"`
+	ErrorCode     *string  `json:"error_code,omitempty"`
+	Message       *string  `json:"message,omitempty"`
+	Retryable     bool     `json:"retryable"`
+}
+
+type InstallResponse struct {
+	OK      bool                     `json:"ok"`
+	Code    int                      `json:"code"`
+	Results []AgentInstallResult     `json:"results"`
+	Log     string                   `json:"log"`
+	Next    string                   `json:"next"`
+	Probe   *ProbeResponse           `json:"probe"`
+	Probes  map[string]ProbeResponse `json:"probes"`
+}
+
+type ActivateRequest struct {
+	AgentID        string `json:"agent_id"`
+	Provider       string `json:"provider"`
+	APIBaseURL     string `json:"api_base_url"`
+	APIKey         string `json:"api_key"`
+	Model          string `json:"model"`
+	ProfileID      string `json:"profile_id"`
+	SmallFastModel string `json:"small_fast_model"`
+}
+
+type ActivateResponse struct {
+	OK       bool   `json:"ok"`
+	Agent    string `json:"agent"`
+	Config   string `json:"config"`
+	Provider string `json:"provider"`
+	Model    string `json:"model"`
+	Restart  string `json:"restart"`
+	Next     string `json:"next"`
+}
+
+type SaveProfileRequest struct {
+	ID         string   `json:"id"`
+	Label      string   `json:"label"`
+	Provider   string   `json:"provider"`
+	APIBaseURL string   `json:"api_base_url"`
+	APIKey     string   `json:"api_key"`
+	Model      string   `json:"model"`
+	ConfigMode string   `json:"config_mode"`
+	AgentIDs   []string `json:"agent_ids"`
+}
+
+func contextError(ctx context.Context) error {
+	if err := ctx.Err(); err != nil {
+		return oneerrors.New(oneerrors.Timeout, "Request was cancelled", oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+	}
+	return nil
+}
+
+func notReady(message string) error {
+	return oneerrors.New(oneerrors.InternalError, strings.TrimSpace(message), oneerrors.WithStatus(501))
+}
+
+func probeResponse(result provider.ProbeResult) ProbeResponse {
+	return ProbeResponse{
+		OK:        result.OK,
+		Reachable: result.Reachable,
+		Status:    result.Status,
+		Message:   result.Message,
+		ErrorCode: result.ErrorCode,
+		Retryable: result.Retryable,
+		Protocol:  result.Protocol,
+	}
+}
+
+func modelsResponse(result provider.ModelsResult) ModelsResponse {
+	return ModelsResponse{
+		ProbeResponse: ProbeResponse{
+			OK:        result.OK,
+			Reachable: result.Reachable,
+			Status:    result.Status,
+			Message:   result.Message,
+			ErrorCode: result.ErrorCode,
+			Retryable: result.Retryable,
+			Protocol:  result.Protocol,
+		},
+		Models: result.Models,
+	}
+}
+
+func installResponse(result app.InstallAgentsResult) InstallResponse {
+	response := InstallResponse{
+		OK:      result.OK,
+		Code:    result.Code,
+		Log:     result.Log,
+		Next:    result.Next,
+		Results: make([]AgentInstallResult, 0, len(result.Results)),
+		Probes:  make(map[string]ProbeResponse, len(result.Probes)),
+	}
+	for _, item := range result.Results {
+		response.Results = append(response.Results, installResult(item))
+	}
+	if result.Probe != nil {
+		probe := probeResponse(*result.Probe)
+		response.Probe = &probe
+	}
+	for protocolID, verdict := range result.Probes {
+		response.Probes[protocolID] = probeResponse(verdict)
+	}
+	return response
+}
+
+func installResult(item app.AgentInstallResult) AgentInstallResult {
+	result := AgentInstallResult{
+		Agent:     item.Agent,
+		Status:    item.Status,
+		Retryable: item.Retryable,
+	}
+	if item.Status == "configured" || item.Status == "skipped" || item.Status == "installed" {
+		if !item.IsCheckOnly() {
+			result.Config = new(item.Config)
+		}
+		result.Installed = new(item.Installed)
+		result.Version = nullableStringPointer(item.Version)
+		result.LockedVersion = nullableStringPointer(item.LockedVersion)
+		if item.Registry != "" {
+			result.Registry = new(item.Registry)
+		}
+	}
+	switch item.Status {
+	case "failed":
+		result.Code = new(item.Code)
+		result.ErrorCode = new(item.ErrorCode)
+		result.Message = new(item.Message)
+	case "guide-only":
+		result.Message = new(item.Message)
+	}
+	return result
+}
+
+func nullableStringPointer(value string) **string {
+	if value == "" {
+		var nilValue *string
+		return &nilValue
+	}
+	valuePointer := &value
+	return &valuePointer
+}
diff --git a/internal/binding/services_test.go b/internal/binding/services_test.go
new file mode 100644
index 00000000..ebfa1a3c
--- /dev/null
+++ b/internal/binding/services_test.go
@@ -0,0 +1,378 @@
+package binding
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"reflect"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/MaimoryLab/OneAgent/internal/app"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+)
+
+type providerFakeDoer func(*http.Request) (*http.Response, error)
+
+func (fake providerFakeDoer) Do(request *http.Request) (*http.Response, error) {
+	return fake(request)
+}
+
+func providerResponse(status int, body string) *http.Response {
+	return &http.Response{StatusCode: status, Body: io.NopCloser(strings.NewReader(body)), Header: make(http.Header)}
+}
+
+func providerCore(t *testing.T, client *provider.Client) *app.UseCases {
+	t.Helper()
+	return app.NewUseCasesWithProviderClient(app.StatusOptions{
+		Home:     t.TempDir(),
+		Platform: platform.For("linux", "amd64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	}, client)
+}
+
+func TestServiceMethodAllowlist(t *testing.T) {
+	tests := []struct {
+		service any
+		want    []string
+	}{
+		{&StatusService{}, []string{"GetStatus"}},
+		{&ProviderService{}, []string{"DeleteProvider", "GetProvider", "ListModels", "OpenRegistration", "Probe", "SaveProvider"}},
+		{&AgentService{}, []string{"Activate", "Install"}},
+		{&ProfileService{}, []string{"ListProfiles", "SaveProfile"}},
+	}
+	for _, test := range tests {
+		typeOf := reflect.TypeOf(test.service)
+		got := make([]string, 0, typeOf.NumMethod())
+		for method := range typeOf.Methods() {
+			got = append(got, method.Name)
+		}
+		sort.Strings(got)
+		sort.Strings(test.want)
+		if !reflect.DeepEqual(got, test.want) {
+			t.Errorf("%s methods = %v, want %v", typeOf, got, test.want)
+		}
+	}
+}
+
+func TestStatusServiceRunsNativeSmokeHookAfterSuccess(t *testing.T) {
+	called := 0
+	service := NewServicesWithOptions(app.NewUseCases(app.StatusOptions{
+		Home:     t.TempDir(),
+		Platform: platform.For("linux", "amd64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	}), nil, ServicesOptions{AfterGetStatus: func() { called++ }}).Status
+	if _, err := service.GetStatus(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if called != 1 {
+		t.Fatalf("native smoke hook calls = %d, want 1", called)
+	}
+
+	if _, err := (&StatusService{afterGetStatus: func() { called++ }}).GetStatus(context.Background()); err == nil {
+		t.Fatal("unconfigured status service succeeded")
+	}
+	if called != 1 {
+		t.Fatalf("native smoke hook ran after failed status = %d", called)
+	}
+}
+
+func TestOpenRegistrationUsesConfiguredProviderURL(t *testing.T) {
+	var opened string
+	service := NewProviderService(providerCore(t, nil), func(value string) error {
+		opened = value
+		return nil
+	})
+	response, err := service.OpenRegistration(context.Background(), OpenRegistrationRequest{Provider: "ppio"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if opened != "https://ppio.com/" || response.URL != opened {
+		t.Fatalf("unexpected registration URL: opened=%q response=%#v", opened, response)
+	}
+
+	_, err = service.OpenRegistration(context.Background(), OpenRegistrationRequest{Provider: "https://example.com"})
+	if err == nil || oneerrors.As(err).Code != oneerrors.InvalidRequest {
+		t.Fatalf("arbitrary URL was not rejected: %v", err)
+	}
+}
+
+func TestProviderServicePersistsCRUDAndReturnsKeyOnlyOnExplicitRead(t *testing.T) {
+	home := t.TempDir()
+	core := app.NewUseCases(app.StatusOptions{
+		Home: home, Platform: platform.For("linux", "amd64"),
+		Lookup: func(string) (string, bool) { return "", false },
+	})
+	service := NewProviderService(core, nil)
+	request := SaveProviderRequest{
+		ID: "acme", Name: "Acme", Home: "https://acme.test/",
+		BaseURL: "https://api.acme.test/openai", APIKey: "sk-provider",
+	}
+	if saved, err := service.SaveProvider(context.Background(), request); err != nil || saved.ID != "acme" {
+		t.Fatalf("saved Provider = %#v, err=%v", saved, err)
+	}
+	entry, err := service.GetProvider(context.Background(), ProviderIDRequest{ID: "acme"})
+	if err != nil || entry.APIKey != "sk-provider" {
+		t.Fatalf("read Provider = %#v, err=%v", entry, err)
+	}
+	status, err := core.GetStatus(context.Background())
+	wire, marshalErr := json.Marshal(status)
+	if err != nil || marshalErr != nil || strings.Contains(string(wire), "sk-provider") || !status.Providers["acme"].HasKey {
+		t.Fatalf("Provider status leaked key: %s, err=%v/%v", wire, err, marshalErr)
+	}
+	deleted, err := service.DeleteProvider(context.Background(), ProviderIDRequest{ID: "acme"})
+	if err != nil || !deleted.OK {
+		t.Fatalf("delete Provider = %#v, err=%v", deleted, err)
+	}
+	if _, err := service.GetProvider(context.Background(), ProviderIDRequest{ID: "acme"}); err == nil {
+		t.Fatal("deleted Provider was still available")
+	}
+}
+
+func TestServiceCancellationUsesStableTimeoutCode(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err := (&ProviderService{}).Probe(ctx, ProbeRequest{})
+	if err == nil || oneerrors.As(err).Code != oneerrors.Timeout {
+		t.Fatalf("cancellation error = %v", err)
+	}
+}
+
+func TestProfileServiceListsPublicSummaries(t *testing.T) {
+	home := t.TempDir()
+	profilesDir := filepath.Join(home, ".oneagent", "profiles")
+	if err := os.MkdirAll(profilesDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(profilesDir, "team.json"), []byte(`{"schema_version":2,"id":"team","label":"Team","provider":"ppio","base_url":null,"model":"model","config_mode":"provider","agent_ids":["codex"]}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	secretDir := filepath.Join(home, ".oneagent", "secrets")
+	if err := os.MkdirAll(secretDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(secretDir, "team.env"), []byte("export ONEAGENT_API_KEY=sk-secret\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	core := app.NewUseCases(app.StatusOptions{
+		Home:     home,
+		Platform: platform.For("linux", "amd64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	})
+	service := NewProfileService(core)
+	profiles, err := service.ListProfiles(context.Background())
+	if err != nil || len(profiles) != 1 || profiles[0].ID != "team" || !profiles[0].HasKey {
+		t.Fatalf("profiles = %#v, err=%v", profiles, err)
+	}
+	wire, err := json.Marshal(profiles)
+	if err != nil || strings.Contains(string(wire), "sk-secret") || strings.Contains(string(wire), "api_key") {
+		t.Fatalf("profile listing leaked secret data: %s (%v)", wire, err)
+	}
+}
+
+func TestProfileServiceSavesWithoutReturningSecret(t *testing.T) {
+	core := app.NewUseCases(app.StatusOptions{
+		Home:     t.TempDir(),
+		Platform: platform.For("linux", "amd64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	})
+	service := NewProfileService(core)
+	summary, err := service.SaveProfile(context.Background(), SaveProfileRequest{
+		ID:         "team",
+		Label:      "Team",
+		Provider:   "ppio",
+		Model:      "model-a",
+		APIKey:     "sk-secret",
+		ConfigMode: "provider",
+		AgentIDs:   []string{"codex"},
+	})
+	if err != nil || summary.ID != "team" || !summary.HasKey {
+		t.Fatalf("saved profile = %#v, err=%v", summary, err)
+	}
+	wire, err := json.Marshal(summary)
+	if err != nil || strings.Contains(string(wire), "sk-secret") || strings.Contains(string(wire), "api_key") {
+		t.Fatalf("binding response leaked secret data: %s (%v)", wire, err)
+	}
+}
+
+func TestAgentServiceActivatesThroughGoUseCase(t *testing.T) {
+	home := t.TempDir()
+	core := app.NewUseCases(app.StatusOptions{
+		Home:     home,
+		Platform: platform.For("linux", "amd64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	})
+	service := NewAgentService(core)
+	response, err := service.Activate(context.Background(), ActivateRequest{
+		AgentID:  "codex",
+		Provider: "ppio",
+		APIKey:   "binding-secret",
+		Model:    "model-a",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !response.OK || response.Agent != "codex" || response.Provider != "ppio" || response.Model != "model-a" {
+		t.Fatalf("activation response = %#v", response)
+	}
+	wire, err := json.Marshal(response)
+	if err != nil || strings.Contains(string(wire), "binding-secret") || strings.Contains(string(wire), "api_key") {
+		t.Fatalf("activation binding response leaked secret material: %s (%v)", wire, err)
+	}
+	if _, err := os.Stat(filepath.Join(home, ".codex", "config.toml")); err != nil {
+		t.Fatalf("Go activation did not write Codex config: %v", err)
+	}
+}
+
+func TestAgentServiceInstallsThroughGoUseCase(t *testing.T) {
+	home := t.TempDir()
+	core := app.NewUseCases(app.StatusOptions{
+		Home:     home,
+		Platform: platform.For("linux", "amd64"),
+		Lookup:   func(string) (string, bool) { return "", false },
+	})
+	service := NewAgentService(core)
+	response, err := service.Install(context.Background(), InstallRequest{
+		Agents:        []string{"codex"},
+		ProfileAgents: []string{"codex"},
+		Provider:      "ppio",
+		APIKey:        "binding-install-secret",
+		Model:         "model-a",
+		Configure:     true,
+		SkipTest:      true,
+		Timeout:       30,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !response.OK || len(response.Results) != 1 || response.Results[0].Status != "configured" {
+		t.Fatalf("install response = %#v", response)
+	}
+	wire, err := json.Marshal(response)
+	if err != nil || strings.Contains(string(wire), "binding-install-secret") || strings.Contains(string(wire), "api_key") {
+		t.Fatalf("install binding response leaked secret material: %s (%v)", wire, err)
+	}
+	if !strings.Contains(string(wire), `"installed":false`) || !strings.Contains(string(wire), `"version":`) {
+		t.Fatalf("install binding response lost established result fields: %s", wire)
+	}
+	if _, err := os.Stat(filepath.Join(home, ".oneagent", "profile.json")); err != nil {
+		t.Fatalf("Go install did not publish profile: %v", err)
+	}
+}
+
+func TestInstallResultBindingPreservesFieldPresence(t *testing.T) {
+	tests := []struct {
+		name string
+		item app.AgentInstallResult
+		want string
+	}{
+		{
+			name: "automatic",
+			item: app.AgentInstallResult{
+				Agent: "codex", Status: "configured", Config: "/tmp/config.json",
+				Installed: false, LockedVersion: "0.145.0",
+			},
+			want: `{"agent":"codex","status":"configured","config":"/tmp/config.json","installed":false,"version":null,"lockedVersion":"0.145.0","retryable":false}`,
+		},
+		{
+			name: "guide-only",
+			item: app.AgentInstallResult{Agent: "gemini-cli", Status: "guide-only", Message: "use login"},
+			want: `{"agent":"gemini-cli","status":"guide-only","message":"use login","retryable":false}`,
+		},
+		{
+			name: "failed",
+			item: app.AgentInstallResult{
+				Agent: "codex", Status: "failed", Code: 7, ErrorCode: "AGENT_INSTALL_FAILED",
+				Message: "npm missing", Retryable: true,
+			},
+			want: `{"agent":"codex","status":"failed","code":7,"error_code":"AGENT_INSTALL_FAILED","message":"npm missing","retryable":true}`,
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			wire, err := json.Marshal(installResult(test.item))
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got := string(wire); got != test.want {
+				t.Fatalf("wire = %s, want %s", got, test.want)
+			}
+		})
+	}
+}
+
+func TestProviderServiceAggregatesSelectedAgentProtocols(t *testing.T) {
+	seen := make([]string, 0)
+	client := provider.NewClient(providerFakeDoer(func(request *http.Request) (*http.Response, error) {
+		seen = append(seen, request.URL.Path)
+		return providerResponse(http.StatusNoContent, ""), nil
+	}))
+	service := NewProviderService(providerCore(t, client), nil)
+	result, err := service.Probe(context.Background(), ProbeRequest{
+		Provider:   "custom",
+		APIBaseURL: "https://proxy.test/v1",
+		APIKey:     "key",
+		Model:      "model",
+		Agents:     []string{"codex", "claude-code", "opencode"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !result.OK || len(result.Protocols) != 3 || result.ErrorCode != nil {
+		t.Fatalf("aggregated probe = %#v", result)
+	}
+	sort.Strings(seen)
+	if !reflect.DeepEqual(seen, []string{"/v1/chat/completions", "/v1/messages", "/v1/responses"}) {
+		t.Fatalf("probe paths = %v", seen)
+	}
+	if result.Protocol == nil || *result.Protocol != "anthropic" {
+		t.Fatalf("primary protocol = %v", result.Protocol)
+	}
+	wire, err := json.Marshal(result)
+	if err != nil || strings.Contains(string(wire), "key") {
+		t.Fatalf("probe response leaked input: %s (%v)", wire, err)
+	}
+	if strings.Count(string(wire), `"protocols"`) != 1 {
+		t.Fatalf("nested probe results must omit empty protocol maps: %s", wire)
+	}
+}
+
+func TestProviderServiceUsesStableFailureAsPrimary(t *testing.T) {
+	client := provider.NewClient(providerFakeDoer(func(request *http.Request) (*http.Response, error) {
+		if request.URL.Path == "/v1/responses" {
+			return providerResponse(http.StatusBadRequest, `{"message":"does not support endpoint"}`), nil
+		}
+		return providerResponse(http.StatusNoContent, ""), nil
+	}))
+	service := NewProviderService(providerCore(t, client), nil)
+	result, err := service.Probe(context.Background(), ProbeRequest{
+		Provider: "custom", APIBaseURL: "https://proxy.test/v1", APIKey: "key", Model: "model", Agents: []string{"codex", "opencode"},
+	})
+	if err != nil || result.OK || result.ErrorCode == nil || *result.ErrorCode != oneerrors.ProtocolUnsupported {
+		t.Fatalf("failure probe = %#v, err=%v", result, err)
+	}
+	if len(result.Protocols) != 2 || result.Protocols["responses"].OK {
+		t.Fatalf("protocol details = %#v", result.Protocols)
+	}
+}
+
+func TestProviderServiceListsModels(t *testing.T) {
+	client := provider.NewClient(providerFakeDoer(func(*http.Request) (*http.Response, error) {
+		return providerResponse(http.StatusOK, `{"data":[{"id":"chat-model"}]}`), nil
+	}))
+	service := NewProviderService(providerCore(t, client), nil)
+	result, err := service.ListModels(context.Background(), ModelsRequest{Provider: "ppio", APIKey: "key"})
+	if err != nil || !result.OK || !reflect.DeepEqual(result.Models, []string{"chat-model"}) {
+		t.Fatalf("models = %#v, err=%v", result, err)
+	}
+	wire, err := json.Marshal(result)
+	if err != nil || strings.Contains(string(wire), `"protocol"`) || !strings.Contains(string(wire), `"error_code":null`) {
+		t.Fatalf("model response null/omitted fields diverged: %s (%v)", wire, err)
+	}
+}
diff --git a/internal/catalog/catalog_test.go b/internal/catalog/catalog_test.go
new file mode 100644
index 00000000..0e2045de
--- /dev/null
+++ b/internal/catalog/catalog_test.go
@@ -0,0 +1,128 @@
+package catalog
+
+import (
+	"encoding/json"
+	"reflect"
+	"sort"
+	"testing"
+)
+
+func TestEmbeddedManifestMatchesCurrentCatalogContract(t *testing.T) {
+	manifest, err := LoadEmbedded()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if manifest.SchemaVersion != SchemaVersion {
+		t.Fatalf("schema = %d", manifest.SchemaVersion)
+	}
+	automatic := 0
+	for id, agent := range manifest.Agents {
+		if agent.ConfigMode == "auto" {
+			automatic++
+			if agent.Package == nil || agent.ConfigAdapter == "" {
+				t.Errorf("auto Agent %s has incomplete contract", id)
+			}
+		}
+	}
+	if automatic != 5 {
+		t.Fatalf("automatic Agent count = %d, want 5", automatic)
+	}
+	items := PublicCatalog(manifest, "windows")
+	if len(items) != len(manifest.Agents) {
+		t.Fatalf("catalog length = %d", len(items))
+	}
+	for index := 1; index < len(items); index++ {
+		if items[index-1].Rank > items[index].Rank || (items[index-1].Rank == items[index].Rank && items[index-1].ID > items[index].ID) {
+			t.Fatalf("catalog is not deterministic: %#v", items)
+		}
+	}
+}
+
+func TestEmbeddedProvidersMatchCurrentCatalogContract(t *testing.T) {
+	manifest, err := LoadEmbeddedProviders()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if manifest.SchemaVersion != ProviderSchemaVersion || len(manifest.Providers) == 0 {
+		t.Fatalf("provider manifest = %#v", manifest)
+	}
+	for id, provider := range manifest.Providers {
+		if provider.Name == "" || provider.BaseURL == "" || provider.fallbackModel == "" {
+			t.Fatalf("provider %q is incomplete: %#v", id, provider)
+		}
+	}
+	ids := ProviderIDs()
+	wantIDs := make([]string, 0, len(manifest.Providers))
+	for id := range manifest.Providers {
+		wantIDs = append(wantIDs, id)
+	}
+	sort.Strings(wantIDs)
+	if !reflect.DeepEqual(ids, wantIDs) {
+		t.Fatalf("ProviderIDs() = %v, want %v", ids, wantIDs)
+	}
+	if got := FallbackProbeModel("unknown"); got != manifest.DefaultFallbackProbeModel {
+		t.Fatalf("unknown fallback = %q, want %q", got, manifest.DefaultFallbackProbeModel)
+	}
+}
+
+func TestPublicProjectionDoesNotExposeFallbackModel(t *testing.T) {
+	providers := PublicProviders()
+	data, err := json.Marshal(providers)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(data) == "" || contains(string(data), "fallback") || contains(string(data), "deepseek") {
+		t.Fatalf("internal provider fields leaked: %s", data)
+	}
+}
+
+func TestParseRejectsInvalidManifest(t *testing.T) {
+	for _, data := range []string{
+		`{"schema_version":2,"agents":{}}`,
+		`{"schema_version":1,"agents":{"bad id":{"name":"Bad","config_mode":"guide","guide":"x","platforms":["linux"],"rank":1}}}`,
+	} {
+		if _, err := Parse([]byte(data)); err == nil {
+			t.Errorf("Parse(%s) unexpectedly succeeded", data)
+		}
+	}
+}
+
+func TestParseProvidersRejectsInvalidEntries(t *testing.T) {
+	tests := []string{
+		`{"schema_version":2,"providers":{}}`,
+		`{"schema_version":1,"default_fallback_probe_model":"m","providers":{"bad id":{"name":"Bad","home":"https://example.com","base_url":"https://api.example.com","fallback_probe_model":"m"}}}`,
+		`{"schema_version":1,"default_fallback_probe_model":"m","providers":{"ok":{"name":"OK","home":"http://example.com","base_url":"https://api.example.com","fallback_probe_model":"m"}}}`,
+		`{"schema_version":1,"default_fallback_probe_model":"m","providers":{"ok":{"name":"OK","home":"https://example.com","base_url":"https://api.example.com","fallback_probe_model":""}}}`,
+	}
+	for _, data := range tests {
+		if _, err := ParseProviders([]byte(data)); err == nil {
+			t.Errorf("ParseProviders(%s) unexpectedly succeeded", data)
+		}
+	}
+}
+
+func TestParsePreservesDeclaredAgentOrder(t *testing.T) {
+	manifest, err := Parse([]byte(`{
+		"schema_version": 1,
+		"agents": {
+			"z-agent": {"name":"Z","config_mode":"guide","guide":"z","platforms":["linux"],"rank":2},
+			"a-agent": {"name":"A","config_mode":"guide","guide":"a","platforms":["linux"],"rank":1}
+		}
+	}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []string{"z-agent", "a-agent"}
+	if got := AgentIDs(manifest); !reflect.DeepEqual(got, want) {
+		t.Fatalf("AgentIDs() = %v, want declaration order %v", got, want)
+	}
+}
+
+func contains(value, needle string) bool {
+	for index := 0; index+len(needle) <= len(value); index++ {
+		if value[index:index+len(needle)] == needle {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/catalog/manifest.go b/internal/catalog/manifest.go
new file mode 100644
index 00000000..4ede1741
--- /dev/null
+++ b/internal/catalog/manifest.go
@@ -0,0 +1,233 @@
+package catalog
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"maps"
+	"net/url"
+	"os"
+	"regexp"
+	"sort"
+	"strings"
+
+	oneagent "github.com/MaimoryLab/OneAgent"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+)
+
+const SchemaVersion = 1
+
+var agentIDPattern = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
+
+func LoadEmbedded() (Manifest, error) {
+	data, err := oneagent.EmbeddedAgentLock()
+	if err != nil {
+		return Manifest{}, oneerrors.New(
+			oneerrors.InvalidRequest,
+			"Cannot load embedded Agent lock manifest",
+			oneerrors.WithCause(err),
+		)
+	}
+	return Parse(data)
+}
+
+func Load(path string) (Manifest, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return Manifest{}, oneerrors.New(
+			oneerrors.InvalidRequest,
+			fmt.Sprintf("Cannot load Agent lock manifest: %v", err),
+			oneerrors.WithCause(err),
+		)
+	}
+	return Parse(data)
+}
+
+func Parse(data []byte) (Manifest, error) {
+	var manifest Manifest
+	if err := json.Unmarshal(data, &manifest); err != nil {
+		return Manifest{}, oneerrors.New(
+			oneerrors.InvalidRequest,
+			fmt.Sprintf("Cannot load Agent lock manifest: %v", err),
+			oneerrors.WithCause(err),
+		)
+	}
+	order, err := decodeAgentOrder(data)
+	if err != nil {
+		return Manifest{}, oneerrors.New(
+			oneerrors.InvalidRequest,
+			fmt.Sprintf("Cannot load Agent lock manifest: %v", err),
+			oneerrors.WithCause(err),
+		)
+	}
+	manifest.AgentOrder = order
+	if err := validate(manifest); err != nil {
+		return Manifest{}, err
+	}
+	return cloneManifest(manifest), nil
+}
+
+func decodeAgentOrder(data []byte) ([]string, error) {
+	var document struct {
+		Agents json.RawMessage `json:"agents"`
+	}
+	if err := json.Unmarshal(data, &document); err != nil {
+		return nil, err
+	}
+	if len(document.Agents) == 0 || bytes.Equal(bytes.TrimSpace(document.Agents), []byte("null")) {
+		return nil, nil
+	}
+	decoder := json.NewDecoder(bytes.NewReader(document.Agents))
+	token, err := decoder.Token()
+	if err != nil {
+		return nil, err
+	}
+	if delimiter, ok := token.(json.Delim); !ok || delimiter != '{' {
+		return nil, fmt.Errorf("agents must be an object")
+	}
+	order := make([]string, 0)
+	seen := make(map[string]bool)
+	for decoder.More() {
+		key, err := decoder.Token()
+		if err != nil {
+			return nil, err
+		}
+		id, ok := key.(string)
+		if !ok {
+			return nil, fmt.Errorf("Agent ID must be a string")
+		}
+		if !seen[id] {
+			order = append(order, id)
+			seen[id] = true
+		}
+		var value json.RawMessage
+		if err := decoder.Decode(&value); err != nil {
+			return nil, err
+		}
+	}
+	if _, err := decoder.Token(); err != nil {
+		return nil, err
+	}
+	return order, nil
+}
+
+func validate(manifest Manifest) error {
+	if manifest.SchemaVersion != SchemaVersion || manifest.Agents == nil {
+		return oneerrors.New(oneerrors.InvalidRequest, "Unsupported Agent lock manifest schema")
+	}
+	if len(manifest.Agents) == 0 {
+		return oneerrors.New(oneerrors.InvalidRequest, "Agent lock manifest has no Agents")
+	}
+	for id, agent := range manifest.Agents {
+		if !agentIDPattern.MatchString(id) {
+			return invalidManifest(id, "invalid Agent ID")
+		}
+		if strings.TrimSpace(agent.Name) == "" {
+			return invalidManifest(id, "name is required")
+		}
+		if agent.ConfigMode != "auto" && agent.ConfigMode != "guide" {
+			return invalidManifest(id, "config_mode must be auto or guide")
+		}
+		if agent.Rank <= 0 {
+			return invalidManifest(id, "rank must be positive")
+		}
+		if len(agent.Platforms) == 0 {
+			return invalidManifest(id, "platforms must not be empty")
+		}
+		for _, platformID := range agent.Platforms {
+			if platformID != "macos" && platformID != "linux" && platformID != "windows" {
+				return invalidManifest(id, "platforms contains an unsupported value")
+			}
+		}
+		if agent.ConfigMode == "guide" {
+			if agent.Package != nil || agent.ConfigAdapter != "" || strings.TrimSpace(agent.Guide) == "" {
+				return invalidManifest(id, "guide Agent has an installation contract")
+			}
+			continue
+		}
+		if agent.Command == "" || agent.ConfigPath == "" || agent.ConfigAdapter == "" || agent.Package == nil {
+			return invalidManifest(id, "auto Agent is missing an installation field")
+		}
+		if err := validatePackage(id, *agent.Package); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func validatePackage(agentID string, pkg Package) error {
+	if pkg.Manager != "npm" && pkg.Manager != "uv" {
+		return invalidManifest(agentID, "package manager is not allowlisted")
+	}
+	if pkg.Name == "" || pkg.Version == "" || pkg.Version == "latest" || pkg.License == "" {
+		return invalidManifest(agentID, "package metadata is incomplete")
+	}
+	if !httpsURL(pkg.Source) || !httpsURL(pkg.LicenseURL) {
+		return invalidManifest(agentID, "package source and license URL must use HTTPS")
+	}
+	if pkg.Manager == "npm" && (pkg.Integrity == nil || !strings.HasPrefix(*pkg.Integrity, "sha512-")) {
+		return invalidManifest(agentID, "npm package integrity must use sha512")
+	}
+	return nil
+}
+
+func httpsURL(value string) bool {
+	parsed, err := url.Parse(value)
+	return err == nil && parsed.Scheme == "https" && parsed.Host != "" && parsed.User == nil
+}
+
+func invalidManifest(agentID, message string) error {
+	return oneerrors.New(oneerrors.InvalidRequest, fmt.Sprintf("Invalid Agent lock manifest entry %s: %s", agentID, message))
+}
+
+func cloneManifest(source Manifest) Manifest {
+	result := source
+	result.AgentOrder = append([]string(nil), source.AgentOrder...)
+	result.Agents = make(map[string]Agent, len(source.Agents))
+	for id, agent := range source.Agents {
+		copyAgent := agent
+		copyAgent.EnvVars = cloneMap(agent.EnvVars)
+		copyAgent.VersionArgs = append([]string(nil), agent.VersionArgs...)
+		copyAgent.Platforms = append([]string(nil), agent.Platforms...)
+		copyAgent.WindowsPrerequisites = append([]string(nil), agent.WindowsPrerequisites...)
+		if agent.Package != nil {
+			copyPackage := *agent.Package
+			if agent.Package.Integrity != nil {
+				integrity := *agent.Package.Integrity
+				copyPackage.Integrity = &integrity
+			}
+			copyAgent.Package = &copyPackage
+		}
+		result.Agents[id] = copyAgent
+	}
+	return result
+}
+
+func cloneMap(source map[string]string) map[string]string {
+	if source == nil {
+		return nil
+	}
+	result := make(map[string]string, len(source))
+	maps.Copy(result, source)
+	return result
+}
+
+func AgentIDs(manifest Manifest) []string {
+	ids := make([]string, 0, len(manifest.Agents))
+	seen := make(map[string]bool, len(manifest.Agents))
+	for _, id := range manifest.AgentOrder {
+		if _, ok := manifest.Agents[id]; ok && !seen[id] {
+			ids = append(ids, id)
+			seen[id] = true
+		}
+	}
+	missing := make([]string, 0, len(manifest.Agents)-len(ids))
+	for id := range manifest.Agents {
+		if !seen[id] {
+			missing = append(missing, id)
+		}
+	}
+	sort.Strings(missing)
+	ids = append(ids, missing...)
+	return ids
+}
diff --git a/internal/catalog/providers.go b/internal/catalog/providers.go
new file mode 100644
index 00000000..64538349
--- /dev/null
+++ b/internal/catalog/providers.go
@@ -0,0 +1,136 @@
+package catalog
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+
+	oneagent "github.com/MaimoryLab/OneAgent"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+)
+
+const ProviderSchemaVersion = 1
+
+// Provider definitions are embedded build-time data. A malformed lock file
+// fails package initialization rather than silently leaving the app without
+// endpoints.
+var providerDefinitions, defaultFallbackProbeModel = mustLoadEmbeddedProviders()
+
+type providerFileEntry struct {
+	Name               string `json:"name"`
+	Home               string `json:"home"`
+	BaseURL            string `json:"base_url"`
+	AnthropicBaseURL   string `json:"anthropic_base_url"`
+	FallbackProbeModel string `json:"fallback_probe_model"`
+}
+
+type providerFile struct {
+	SchemaVersion             int                          `json:"schema_version"`
+	DefaultFallbackProbeModel string                       `json:"default_fallback_probe_model"`
+	Providers                 map[string]providerFileEntry `json:"providers"`
+}
+
+func LoadEmbeddedProviders() (ProviderManifest, error) {
+	data, err := oneagent.EmbeddedProviderLock()
+	if err != nil {
+		return ProviderManifest{}, oneerrors.New(
+			oneerrors.InvalidRequest,
+			"Cannot load embedded Provider lock manifest",
+			oneerrors.WithCause(err),
+		)
+	}
+	return ParseProviders(data)
+}
+
+func LoadProviders(path string) (ProviderManifest, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return ProviderManifest{}, oneerrors.New(
+			oneerrors.InvalidRequest,
+			fmt.Sprintf("Cannot load Provider lock manifest: %v", err),
+			oneerrors.WithCause(err),
+		)
+	}
+	return ParseProviders(data)
+}
+
+func ParseProviders(data []byte) (ProviderManifest, error) {
+	var source providerFile
+	if err := json.Unmarshal(data, &source); err != nil {
+		return ProviderManifest{}, oneerrors.New(
+			oneerrors.InvalidRequest,
+			fmt.Sprintf("Cannot load Provider lock manifest: %v", err),
+			oneerrors.WithCause(err),
+		)
+	}
+	if err := validateProviders(source); err != nil {
+		return ProviderManifest{}, err
+	}
+	manifest := ProviderManifest{
+		SchemaVersion:             source.SchemaVersion,
+		DefaultFallbackProbeModel: source.DefaultFallbackProbeModel,
+		Providers:                 make(map[string]Provider, len(source.Providers)),
+	}
+	for id, entry := range source.Providers {
+		manifest.Providers[id] = Provider{
+			Name:             entry.Name,
+			Home:             entry.Home,
+			BaseURL:          entry.BaseURL,
+			AnthropicBaseURL: entry.AnthropicBaseURL,
+			fallbackModel:    entry.FallbackProbeModel,
+		}
+	}
+	return cloneProviderManifest(manifest), nil
+}
+
+func validateProviders(source providerFile) error {
+	if source.SchemaVersion != ProviderSchemaVersion || source.Providers == nil {
+		return oneerrors.New(oneerrors.InvalidRequest, "Unsupported Provider lock manifest schema")
+	}
+	if len(source.Providers) == 0 {
+		return oneerrors.New(oneerrors.InvalidRequest, "Provider lock manifest has no Providers")
+	}
+	if strings.TrimSpace(source.DefaultFallbackProbeModel) == "" {
+		return oneerrors.New(oneerrors.InvalidRequest, "Provider lock manifest has no default fallback probe model")
+	}
+	for id, entry := range source.Providers {
+		if !agentIDPattern.MatchString(id) || id == "custom" {
+			return invalidProvider(id, "invalid Provider ID")
+		}
+		if strings.TrimSpace(entry.Name) == "" {
+			return invalidProvider(id, "name is required")
+		}
+		if !httpsURL(entry.Home) || !httpsURL(entry.BaseURL) {
+			return invalidProvider(id, "home and base_url must use HTTPS")
+		}
+		if entry.AnthropicBaseURL != "" && !httpsURL(entry.AnthropicBaseURL) {
+			return invalidProvider(id, "anthropic_base_url must use HTTPS")
+		}
+		if strings.TrimSpace(entry.FallbackProbeModel) == "" {
+			return invalidProvider(id, "fallback_probe_model is required")
+		}
+	}
+	return nil
+}
+
+func invalidProvider(providerID, message string) error {
+	return oneerrors.New(oneerrors.InvalidRequest, fmt.Sprintf("Invalid Provider lock manifest entry %s: %s", providerID, message))
+}
+
+func cloneProviderManifest(source ProviderManifest) ProviderManifest {
+	result := source
+	result.Providers = make(map[string]Provider, len(source.Providers))
+	for id, provider := range source.Providers {
+		result.Providers[id] = provider
+	}
+	return result
+}
+
+func mustLoadEmbeddedProviders() (map[string]Provider, string) {
+	manifest, err := LoadEmbeddedProviders()
+	if err != nil {
+		panic(err)
+	}
+	return manifest.Providers, manifest.DefaultFallbackProbeModel
+}
diff --git a/internal/catalog/public.go b/internal/catalog/public.go
new file mode 100644
index 00000000..0146f80e
--- /dev/null
+++ b/internal/catalog/public.go
@@ -0,0 +1,133 @@
+package catalog
+
+import "sort"
+
+const (
+	ProtocolOpenAI    = "openai"
+	ProtocolAnthropic = "anthropic"
+	ProtocolResponses = "responses"
+)
+
+var adapterProtocols = map[string]string{
+	"codex":       ProtocolResponses,
+	"claude-code": ProtocolAnthropic,
+	"opencode":    ProtocolOpenAI,
+	"kilo-cli":    ProtocolOpenAI,
+	"aider":       ProtocolOpenAI,
+}
+
+var groups = []Group{
+	{ID: "auto", Name: "One-click configurable"},
+	{ID: "gateway", Name: "Gateway agents"},
+	{ID: "platform", Name: "Official account agents"},
+	{ID: "ide", Name: "IDE extensions"},
+}
+
+const officialNPMRegistry = "https://registry.npmjs.org/"
+
+var mirrors = []Mirror{
+	{
+		ID:       "official",
+		Name:     "官方源",
+		Registry: officialNPMRegistry,
+		Upstream: officialNPMRegistry,
+		Note:     "npm 官方 registry，默认使用。",
+	},
+	{
+		ID:       "npmmirror",
+		Name:     "npmmirror（阿里云）",
+		Registry: "https://registry.npmmirror.com/",
+		Upstream: officialNPMRegistry,
+		Note:     "官方源的公开只读镜像，包体与校验值均与官方一致；官方源不可达时可用。",
+	},
+}
+
+func ProtocolForAdapter(adapter string) string {
+	if protocol, ok := adapterProtocols[adapter]; ok {
+		return protocol
+	}
+	return ProtocolOpenAI
+}
+
+func FallbackProbeModel(providerID string) string {
+	if provider, ok := providerDefinitions[providerID]; ok {
+		return provider.fallbackModel
+	}
+	return defaultFallbackProbeModel
+}
+
+func PublicProviders() map[string]Provider {
+	result := make(map[string]Provider, len(providerDefinitions))
+	for id, provider := range providerDefinitions {
+		// fallbackModel is unexported and therefore cannot leak through JSON,
+		// but clear it here as an additional boundary for non-JSON callers.
+		provider.fallbackModel = ""
+		result[id] = provider
+	}
+	return result
+}
+
+func ProviderByID(providerID string) (Provider, bool) {
+	provider, ok := providerDefinitions[providerID]
+	if !ok {
+		return Provider{}, false
+	}
+	provider.fallbackModel = ""
+	return provider, true
+}
+
+func ProviderIDs() []string {
+	ids := make([]string, 0, len(providerDefinitions))
+	for id := range providerDefinitions {
+		ids = append(ids, id)
+	}
+	sort.Strings(ids)
+	return ids
+}
+
+func Groups() []Group {
+	return append([]Group(nil), groups...)
+}
+
+func Mirrors() []Mirror {
+	return append([]Mirror(nil), mirrors...)
+}
+
+func PublicCatalog(manifest Manifest, platformID string) []CatalogItem {
+	items := make([]CatalogItem, 0, len(manifest.Agents))
+	for id, agent := range manifest.Agents {
+		var lockedVersion *string
+		if agent.Package != nil {
+			version := agent.Package.Version
+			lockedVersion = &version
+		}
+		var protocol *string
+		if agent.ConfigMode == "auto" {
+			value := ProtocolForAdapter(agent.ConfigAdapter)
+			protocol = &value
+		}
+		platformNote := ""
+		if platformID == "windows" {
+			platformNote = agent.WindowsNote
+		}
+		items = append(items, CatalogItem{
+			ID:            id,
+			Name:          agent.Name,
+			Group:         agent.Group,
+			ConfigMode:    agent.ConfigMode,
+			GuideOnly:     agent.ConfigMode == "guide",
+			LockedVersion: lockedVersion,
+			Protocol:      protocol,
+			Platforms:     append([]string(nil), agent.Platforms...),
+			PlatformNote:  platformNote,
+			Rank:          agent.Rank,
+		})
+	}
+	sort.Slice(items, func(i, j int) bool {
+		if items[i].Rank != items[j].Rank {
+			return items[i].Rank < items[j].Rank
+		}
+		return items[i].ID < items[j].ID
+	})
+	return items
+}
diff --git a/internal/catalog/runtimes.go b/internal/catalog/runtimes.go
new file mode 100644
index 00000000..2d7c9c29
--- /dev/null
+++ b/internal/catalog/runtimes.go
@@ -0,0 +1,183 @@
+package catalog
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"regexp"
+	"sort"
+	"strings"
+	"sync"
+
+	oneagent "github.com/MaimoryLab/OneAgent"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+)
+
+// RuntimeManifest is the pinned download contract for the package managers
+// OneAgent can bootstrap. It is a lock file for the same reason agents.lock.json
+// is: runtime code must never invent a download URL or accept an unpinned
+// checksum.
+type RuntimeManifest struct {
+	SchemaVersion int                `json:"schema_version"`
+	Runtimes      map[string]Runtime `json:"runtimes"`
+	RuntimeOrder  []string           `json:"-"`
+}
+
+type Runtime struct {
+	Name         string                     `json:"name"`
+	Version      string                     `json:"version"`
+	Commands     []string                   `json:"commands"`
+	ProbeCommand string                     `json:"probe_command"`
+	License      string                     `json:"license"`
+	LicenseURL   string                     `json:"license_url"`
+	Source       string                     `json:"source"`
+	Note         string                     `json:"note"`
+	Artifacts    map[string]RuntimeArtifact `json:"artifacts"`
+}
+
+// RuntimeArtifact is one platform's archive. StripRoot reports whether the
+// archive wraps its payload in a single top-level directory that must be
+// removed; BinDir is the directory inside the installed tree that holds the
+// executables, relative to the stripped root.
+type RuntimeArtifact struct {
+	URL       string `json:"url"`
+	MirrorURL string `json:"mirror_url"`
+	SHA256    string `json:"sha256"`
+	Archive   string `json:"archive"`
+	StripRoot bool   `json:"strip_root"`
+	BinDir    string `json:"bin_dir"`
+}
+
+var (
+	runtimeIDPattern = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
+	sha256Pattern    = regexp.MustCompile(`^[0-9a-f]{64}$`)
+
+	runtimeOnce     sync.Once
+	runtimeManifest RuntimeManifest
+	runtimeErr      error
+)
+
+// RuntimeArtifactKey is the platform key used in runtimes.lock.json. It is
+// built from the same normalized values platform.Info reports so the lock file
+// and the running host cannot disagree about naming.
+func RuntimeArtifactKey(osID, arch string) string {
+	if arch == "" {
+		arch = "x64"
+	}
+	return osID + "-" + arch
+}
+
+// LoadEmbeddedRuntimes parses the embedded runtime lock once and returns a
+// defensive copy. A malformed lock file is a build defect, so the error is
+// returned rather than silently degraded.
+func LoadEmbeddedRuntimes() (RuntimeManifest, error) {
+	runtimeOnce.Do(func() {
+		data, err := oneagent.EmbeddedRuntimeLock()
+		if err != nil {
+			runtimeErr = oneerrors.New(oneerrors.InvalidRequest, "Cannot load embedded runtime lock manifest", oneerrors.WithCause(err))
+			return
+		}
+		runtimeManifest, runtimeErr = ParseRuntimes(data)
+	})
+	if runtimeErr != nil {
+		return RuntimeManifest{}, runtimeErr
+	}
+	return cloneRuntimeManifest(runtimeManifest), nil
+}
+
+func ParseRuntimes(data []byte) (RuntimeManifest, error) {
+	var manifest RuntimeManifest
+	if err := json.Unmarshal(data, &manifest); err != nil {
+		return RuntimeManifest{}, invalidRuntime(fmt.Sprintf("Cannot load runtime lock manifest: %v", err))
+	}
+	if manifest.SchemaVersion != SchemaVersion {
+		return RuntimeManifest{}, invalidRuntime(fmt.Sprintf("Unsupported runtime lock schema_version %d", manifest.SchemaVersion))
+	}
+	if len(manifest.Runtimes) == 0 {
+		return RuntimeManifest{}, invalidRuntime("Runtime lock manifest contains no runtimes")
+	}
+	for id, runtime := range manifest.Runtimes {
+		if err := validateRuntime(id, runtime); err != nil {
+			return RuntimeManifest{}, err
+		}
+	}
+	manifest.RuntimeOrder = sortedKeys(manifest.Runtimes)
+	return cloneRuntimeManifest(manifest), nil
+}
+
+func validateRuntime(id string, runtime Runtime) error {
+	if !runtimeIDPattern.MatchString(id) {
+		return invalidRuntime(fmt.Sprintf("Runtime id %q must be lowercase alphanumeric", id))
+	}
+	if strings.TrimSpace(runtime.Name) == "" || strings.TrimSpace(runtime.Version) == "" {
+		return invalidRuntime(fmt.Sprintf("Runtime %s requires name and version", id))
+	}
+	if len(runtime.Commands) == 0 {
+		return invalidRuntime(fmt.Sprintf("Runtime %s requires at least one command", id))
+	}
+	if runtime.ProbeCommand == "" {
+		return invalidRuntime(fmt.Sprintf("Runtime %s requires probe_command", id))
+	}
+	if len(runtime.Artifacts) == 0 {
+		return invalidRuntime(fmt.Sprintf("Runtime %s requires at least one artifact", id))
+	}
+	for key, artifact := range runtime.Artifacts {
+		if err := validateArtifact(id, key, artifact); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func validateArtifact(runtimeID, key string, artifact RuntimeArtifact) error {
+	for label, value := range map[string]string{"url": artifact.URL, "mirror_url": artifact.MirrorURL} {
+		if value == "" {
+			continue
+		}
+		parsed, err := url.Parse(value)
+		if err != nil || parsed.Scheme != "https" || parsed.Host == "" {
+			return invalidRuntime(fmt.Sprintf("Runtime %s artifact %s %s must be an https URL", runtimeID, key, label))
+		}
+	}
+	if artifact.URL == "" {
+		return invalidRuntime(fmt.Sprintf("Runtime %s artifact %s requires url", runtimeID, key))
+	}
+	if !sha256Pattern.MatchString(artifact.SHA256) {
+		return invalidRuntime(fmt.Sprintf("Runtime %s artifact %s requires a lowercase hex sha256", runtimeID, key))
+	}
+	if artifact.Archive != "tar.gz" && artifact.Archive != "zip" {
+		return invalidRuntime(fmt.Sprintf("Runtime %s artifact %s has unsupported archive %q", runtimeID, key, artifact.Archive))
+	}
+	return nil
+}
+
+func invalidRuntime(message string) error {
+	return oneerrors.New(oneerrors.InvalidRequest, message)
+}
+
+func sortedKeys[V any](source map[string]V) []string {
+	keys := make([]string, 0, len(source))
+	for key := range source {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+func cloneRuntimeManifest(source RuntimeManifest) RuntimeManifest {
+	result := RuntimeManifest{
+		SchemaVersion: source.SchemaVersion,
+		Runtimes:      make(map[string]Runtime, len(source.Runtimes)),
+		RuntimeOrder:  append([]string(nil), source.RuntimeOrder...),
+	}
+	for id, runtime := range source.Runtimes {
+		copied := runtime
+		copied.Commands = append([]string(nil), runtime.Commands...)
+		copied.Artifacts = make(map[string]RuntimeArtifact, len(runtime.Artifacts))
+		for key, artifact := range runtime.Artifacts {
+			copied.Artifacts[key] = artifact
+		}
+		result.Runtimes[id] = copied
+	}
+	return result
+}
diff --git a/internal/catalog/types.go b/internal/catalog/types.go
new file mode 100644
index 00000000..bb31ed1b
--- /dev/null
+++ b/internal/catalog/types.go
@@ -0,0 +1,83 @@
+// Package catalog parses the embedded Agent and Provider lock files and
+// projects them for the desktop shell and the CLI. The lock files are the
+// hand-edited sources, so runtime code does not invent catalog URLs or models.
+package catalog
+
+type Manifest struct {
+	SchemaVersion   int              `json:"schema_version"`
+	OneAgentVersion string           `json:"oneagent_version"`
+	GeneratedAt     string           `json:"generated_at"`
+	Agents          map[string]Agent `json:"agents"`
+	AgentOrder      []string         `json:"-"`
+}
+
+type ProviderManifest struct {
+	SchemaVersion             int                 `json:"schema_version"`
+	DefaultFallbackProbeModel string              `json:"default_fallback_probe_model"`
+	Providers                 map[string]Provider `json:"providers"`
+}
+
+type Agent struct {
+	Name                 string            `json:"name"`
+	Group                string            `json:"group"`
+	Command              string            `json:"command"`
+	ConfigMode           string            `json:"config_mode"`
+	ConfigAdapter        string            `json:"config_adapter"`
+	CredentialDelivery   string            `json:"credential_delivery"`
+	EnvVars              map[string]string `json:"env_vars"`
+	ConfigPath           string            `json:"config_path"`
+	WindowsConfigPath    string            `json:"windows_config_path"`
+	Package              *Package          `json:"package"`
+	VersionArgs          []string          `json:"version_args"`
+	Platforms            []string          `json:"platforms"`
+	WindowsPrerequisites []string          `json:"windows_prerequisites"`
+	WindowsNote          string            `json:"windows_note"`
+	Guide                string            `json:"guide"`
+	Rank                 int               `json:"rank"`
+}
+
+type Package struct {
+	Manager    string  `json:"manager"`
+	Name       string  `json:"name"`
+	Version    string  `json:"version"`
+	Integrity  *string `json:"integrity"`
+	Source     string  `json:"source"`
+	License    string  `json:"license"`
+	LicenseURL string  `json:"license_url"`
+}
+
+type CatalogItem struct {
+	ID            string   `json:"id"`
+	Name          string   `json:"name"`
+	Group         string   `json:"group"`
+	ConfigMode    string   `json:"configMode"`
+	GuideOnly     bool     `json:"guideOnly"`
+	LockedVersion *string  `json:"lockedVersion"`
+	Protocol      *string  `json:"protocol"`
+	Platforms     []string `json:"platforms"`
+	PlatformNote  string   `json:"platformNote"`
+	Rank          int      `json:"rank"`
+}
+
+type Group struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+}
+
+type Provider struct {
+	Name             string `json:"name"`
+	Home             string `json:"home"`
+	BaseURL          string `json:"base_url"`
+	AnthropicBaseURL string `json:"anthropic_base_url,omitempty"`
+	Custom           bool   `json:"custom,omitempty"`
+	HasKey           bool   `json:"has_key,omitempty"`
+	fallbackModel    string
+}
+
+type Mirror struct {
+	ID       string `json:"id"`
+	Name     string `json:"name"`
+	Registry string `json:"registry"`
+	Upstream string `json:"upstream"`
+	Note     string `json:"note"`
+}
diff --git a/internal/config/discovery.go b/internal/config/discovery.go
new file mode 100644
index 00000000..7498ff04
--- /dev/null
+++ b/internal/config/discovery.go
@@ -0,0 +1,194 @@
+// Package config contains read-only projections of Agent configuration files.
+// Readers intentionally extract only endpoint/model metadata; they never
+// return credential values or execute user-controlled scripts.
+package config
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"regexp"
+	"strings"
+
+	"github.com/pelletier/go-toml/v2"
+)
+
+type Detected struct {
+	BaseURL           string  `json:"baseUrl"`
+	Model             string  `json:"model"`
+	ManagedByOneAgent bool    `json:"managedByOneAgent"`
+	Unreadable        *string `json:"unreadable"`
+}
+
+func ReadCodexConfig(text string) Detected {
+	var parsed map[string]any
+	if err := toml.Unmarshal([]byte(text), &parsed); err != nil {
+		return unreadable(fmt.Sprintf("TOML 无法解析：%v", err))
+	}
+	providers, _ := parsed["model_providers"].(map[string]any)
+	selected, _ := parsed["model_provider"].(string)
+	baseURL := ""
+	if table, ok := providers[selected].(map[string]any); ok {
+		if value, ok := table["base_url"].(string); ok {
+			baseURL = value
+		}
+	}
+	model, _ := parsed["model"].(string)
+	_, managed := providers["oneagent"]
+	return Detected{BaseURL: baseURL, Model: model, ManagedByOneAgent: managed}
+}
+
+func ReadClaudeConfig(text string, envVars map[string]string) Detected {
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(text), &parsed); err != nil {
+		return unreadable(fmt.Sprintf("JSON 无法解析：%v", err))
+	}
+	if parsed == nil {
+		return unreadable("配置的顶层不是对象")
+	}
+	env, _ := parsed["env"].(map[string]any)
+	baseKey := envVars["base_url"]
+	if baseKey == "" {
+		baseKey = "ANTHROPIC_BASE_URL"
+	}
+	modelKey := envVars["model"]
+	if modelKey == "" {
+		modelKey = "ANTHROPIC_MODEL"
+	}
+	baseURL, _ := env[baseKey].(string)
+	model, _ := env[modelKey].(string)
+	managed := len(envVars) > 0
+	for _, key := range envVars {
+		value, ok := env[key].(string)
+		if !ok || value == "" {
+			managed = false
+			break
+		}
+	}
+	return Detected{BaseURL: baseURL, Model: model, ManagedByOneAgent: managed}
+}
+
+func ReadOpenAICompatibleConfig(text string) Detected {
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(text), &parsed); err != nil {
+		if jsoncCommentPattern.MatchString(text) {
+			return unreadable("包含 JSONC 注释，OneAgent 不解析")
+		}
+		return unreadable(fmt.Sprintf("JSON 无法解析：%v", err))
+	}
+	if parsed == nil {
+		return unreadable("配置的顶层不是对象")
+	}
+	providers, _ := parsed["provider"].(map[string]any)
+	modelValue, _ := parsed["model"].(string)
+	selected, bareModel := splitModel(modelValue)
+	baseURL := ""
+	if table, ok := providers[selected].(map[string]any); ok {
+		if options, ok := table["options"].(map[string]any); ok {
+			if value, ok := options["baseURL"].(string); ok {
+				baseURL = value
+			}
+		}
+	}
+	_, managed := providers["oneagent"]
+	return Detected{BaseURL: baseURL, Model: bareModel, ManagedByOneAgent: managed}
+}
+
+func ReadAiderConfig(text string) Detected {
+	baseURL := ""
+	for line := range strings.SplitSeq(text, "\n") {
+		trimmed := strings.TrimSpace(line)
+		for _, prefix := range []string{"export OPENAI_API_BASE=", "$env:OPENAI_API_BASE ="} {
+			if !strings.HasPrefix(trimmed, prefix) {
+				continue
+			}
+			value := strings.TrimSpace(strings.TrimPrefix(trimmed, prefix))
+			baseURL = unquoteShellValue(value)
+		}
+	}
+	return Detected{BaseURL: baseURL}
+}
+
+// DetectFile returns nil only when the file is absent. Any present but empty,
+// unreadable, or unknown-format file gets a local diagnostic so one bad Agent
+// cannot fail the entire status request.
+func DetectFile(path, adapter string, envVars map[string]string) *Detected {
+	reader := readerFor(adapter, envVars)
+	if reader == nil {
+		result := unreadable("没有可用的配置解析器")
+		return &result
+	}
+	info, err := os.Stat(path)
+	if os.IsNotExist(err) || err == nil && !info.Mode().IsRegular() {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		result := unreadable("配置文件不是普通文件")
+		return &result
+	}
+	if err != nil {
+		result := unreadable(fmt.Sprintf("无法读取：%v", err))
+		return &result
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		result := unreadable(fmt.Sprintf("无法读取：%v", err))
+		return &result
+	}
+	if strings.TrimSpace(string(data)) == "" {
+		result := unreadable("配置文件为空")
+		return &result
+	}
+	result := safeRead(reader, string(data))
+	return &result
+}
+
+type reader func(string) Detected
+
+func readerFor(adapter string, envVars map[string]string) reader {
+	switch adapter {
+	case "codex":
+		return ReadCodexConfig
+	case "claude-code":
+		return func(text string) Detected { return ReadClaudeConfig(text, envVars) }
+	case "opencode", "kilo-cli":
+		return ReadOpenAICompatibleConfig
+	case "aider":
+		return ReadAiderConfig
+	default:
+		return nil
+	}
+}
+
+func safeRead(read reader, text string) (result Detected) {
+	defer func() {
+		if recover() != nil {
+			result = unreadable("配置解析失败")
+		}
+	}()
+	return read(text)
+}
+
+func unreadable(message string) Detected {
+	return Detected{Unreadable: new(message)}
+}
+
+func splitModel(value string) (string, string) {
+	selected, bare, found := strings.Cut(value, "/")
+	if !found {
+		return "", value
+	}
+	return selected, bare
+}
+
+func unquoteShellValue(value string) string {
+	if len(value) >= 2 && value[0] == '\'' && value[len(value)-1] == '\'' {
+		return strings.ReplaceAll(value[1:len(value)-1], "''", "'")
+	}
+	if len(value) >= 2 && value[0] == '"' && value[len(value)-1] == '"' {
+		return value[1 : len(value)-1]
+	}
+	return value
+}
+
+var jsoncCommentPattern = regexp.MustCompile(`(?m)(^|\s)(//|/\*)`)
diff --git a/internal/config/discovery_test.go b/internal/config/discovery_test.go
new file mode 100644
index 00000000..383ccd20
--- /dev/null
+++ b/internal/config/discovery_test.go
@@ -0,0 +1,109 @@
+package config
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestReadCodexFollowsSelectedProviderAndMarker(t *testing.T) {
+	detected := ReadCodexConfig("model_provider = \"vendor\"\nmodel = \"gpt-5-mini\"\n[model_providers.vendor]\nbase_url = \"https://vendor.example/v1\"\n[model_providers.oneagent]\nbase_url = \"https://ours.example/v1\"\napi_key = \"sk-hidden\"\n")
+	if detected.BaseURL != "https://vendor.example/v1" || detected.Model != "gpt-5-mini" || !detected.ManagedByOneAgent || detected.Unreadable != nil {
+		t.Fatalf("codex detection = %#v", detected)
+	}
+	if strings.Contains(mustJSON(t, detected), "sk-hidden") || strings.Contains(mustJSON(t, detected), "api_key") {
+		t.Fatalf("codex detection leaked secret fields: %#v", detected)
+	}
+}
+
+func TestReadClaudeRequiresAllDeclaredVariablesWithoutReturningKey(t *testing.T) {
+	declared := map[string]string{
+		"api_key":          "ANTHROPIC_AUTH_TOKEN",
+		"base_url":         "ANTHROPIC_BASE_URL",
+		"model":            "ANTHROPIC_MODEL",
+		"small_fast_model": "ANTHROPIC_SMALL_FAST_MODEL",
+	}
+	partial := ReadClaudeConfig(`{"env":{"ANTHROPIC_BASE_URL":"https://x.example"}}`, declared)
+	if partial.BaseURL != "https://x.example" || partial.ManagedByOneAgent {
+		t.Fatalf("partial Claude detection = %#v", partial)
+	}
+	full := ReadClaudeConfig(`{"env":{"ANTHROPIC_AUTH_TOKEN":"sk-secret","ANTHROPIC_BASE_URL":"https://x.example","ANTHROPIC_MODEL":"m","ANTHROPIC_SMALL_FAST_MODEL":"fast"}}`, declared)
+	if !full.ManagedByOneAgent || full.Model != "m" || strings.Contains(mustJSON(t, full), "sk-secret") {
+		t.Fatalf("full Claude detection = %#v", full)
+	}
+}
+
+func TestReadOpenAICompatibleAndJSONC(t *testing.T) {
+	detected := ReadOpenAICompatibleConfig(`{"provider":{"mine":{"options":{"baseURL":"https://mine.example/v1","apiKey":"sk-secret"}}},"model":"mine/local-llm"}`)
+	if detected.BaseURL != "https://mine.example/v1" || detected.Model != "local-llm" {
+		t.Fatalf("OpenAI-compatible detection = %#v", detected)
+	}
+	if detected := ReadOpenAICompatibleConfig("{\n // comment\n \"model\":\"x/y\"\n}"); detected.Unreadable == nil || !strings.Contains(*detected.Unreadable, "JSONC") {
+		t.Fatalf("JSONC detection = %#v", detected)
+	}
+	if detected := ReadOpenAICompatibleConfig(`{"model":"bare-model"}`); detected.Model != "bare-model" {
+		t.Fatalf("bare model detection = %#v", detected)
+	}
+}
+
+func TestReadAiderNeverExecutesOrReturnsKey(t *testing.T) {
+	detected := ReadAiderConfig("export OPENAI_API_BASE='https://hand.example/v1'\nexport OPENAI_API_KEY='sk-never-return'\n")
+	if detected.BaseURL != "https://hand.example/v1" || detected.ManagedByOneAgent || strings.Contains(mustJSON(t, detected), "sk-never-return") {
+		t.Fatalf("Aider detection = %#v", detected)
+	}
+	if got := ReadAiderConfig("$env:OPENAI_API_BASE = \"https://win.example/v1\"\n"); got.BaseURL != "https://win.example/v1" {
+		t.Fatalf("PowerShell detection = %#v", got)
+	}
+}
+
+func TestReadersReturnLocalDiagnosticsForMalformedOrWrongTypes(t *testing.T) {
+	for _, detected := range []Detected{
+		ReadCodexConfig("model_provider = \nbroken ["),
+		ReadClaudeConfig("[]", nil),
+		ReadOpenAICompatibleConfig("[]"),
+		ReadOpenAICompatibleConfig("{ not json"),
+	} {
+		if detected.Unreadable == nil || detected.BaseURL != "" || detected.Model != "" {
+			t.Fatalf("malformed detection = %#v", detected)
+		}
+	}
+	codex := ReadCodexConfig("model_provider = 1\nmodel = 2\n[model_providers.p]\nbase_url = 3\n")
+	if codex.BaseURL != "" || codex.Model != "" {
+		t.Fatalf("wrongly typed TOML values = %#v", codex)
+	}
+}
+
+func TestDetectFileDistinguishesAbsentEmptyUnknownAndSecrets(t *testing.T) {
+	home := t.TempDir()
+	path := filepath.Join(home, "config.toml")
+	if got := DetectFile(path, "codex", nil); got != nil {
+		t.Fatalf("absent detection = %#v", got)
+	}
+	if err := os.WriteFile(path, []byte("  \n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if got := DetectFile(path, "codex", nil); got == nil || got.Unreadable == nil || !strings.Contains(*got.Unreadable, "空") {
+		t.Fatalf("empty detection = %#v", got)
+	}
+	if err := os.WriteFile(path, []byte("model_provider = \"p\"\nmodel = \"m\"\n[model_providers.p]\nbase_url = \"https://example\"\napi_key = \"sk-file-secret\"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	got := DetectFile(path, "codex", nil)
+	if got == nil || got.BaseURL != "https://example" || strings.Contains(mustJSON(t, got), "sk-file-secret") {
+		t.Fatalf("file detection = %#v", got)
+	}
+	if got := DetectFile(path, "future-adapter", nil); got == nil || got.Unreadable == nil {
+		t.Fatalf("unknown adapter detection = %#v", got)
+	}
+}
+
+func mustJSON(t *testing.T, value any) string {
+	t.Helper()
+	data, err := json.Marshal(value)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(data)
+}
diff --git a/internal/config/env.go b/internal/config/env.go
new file mode 100644
index 00000000..b9b18d27
--- /dev/null
+++ b/internal/config/env.go
@@ -0,0 +1,92 @@
+package config
+
+import (
+	"context"
+	"strings"
+
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+func WriteAgentEnv(ctx context.Context, filesystem securefs.Store, path, osID, agentID, apiKey, baseURL, model, smallFastModel string, native map[string]string) error {
+	values := []envValue{
+		{Name: agentEnvVar(agentID), Value: apiKey},
+		{Name: agentEnvVar(agentID, "API_BASE_URL"), Value: baseURL},
+		{Name: "ONEAGENT_API_KEY", Value: apiKey},
+		{Name: "ONEAGENT_API_BASE_URL", Value: baseURL},
+	}
+	fastModel := smallFastModel
+	if fastModel == "" {
+		fastModel = model
+	}
+	for _, item := range []struct{ field, value string }{
+		{field: "api_key", value: apiKey},
+		{field: "base_url", value: baseURL},
+		{field: "model", value: model},
+		{field: "small_fast_model", value: fastModel},
+	} {
+		field, value := item.field, item.value
+		if name := native[field]; name != "" && value != "" {
+			values = append(values, envValue{Name: name, Value: value})
+		}
+	}
+	content := renderEnv(osID, values)
+	if _, err := filesystem.AtomicWrite(ctx, path, []byte(content), true); err != nil {
+		return err
+	}
+	return nil
+}
+
+func WriteSharedEnv(ctx context.Context, filesystem securefs.Store, path, osID, apiKey, baseURL string) error {
+	content := renderEnv(osID, []envValue{
+		{Name: "ONEAGENT_API_KEY", Value: apiKey},
+		{Name: "ONEAGENT_API_BASE_URL", Value: baseURL},
+	})
+	if _, err := filesystem.AtomicWrite(ctx, path, []byte(content), true); err != nil {
+		return err
+	}
+	return nil
+}
+
+type envValue struct {
+	Name  string
+	Value string
+}
+
+func renderEnv(osID string, values []envValue) string {
+	var builder strings.Builder
+	for _, value := range values {
+		if osID == "windows" {
+			builder.WriteString("$env:")
+			builder.WriteString(value.Name)
+			builder.WriteString(" = '")
+			builder.WriteString(powershellQuote(value.Value))
+			builder.WriteString("'\n")
+			continue
+		}
+		builder.WriteString("export ")
+		builder.WriteString(value.Name)
+		builder.WriteByte('=')
+		builder.WriteString(shellQuote(value.Value))
+		builder.WriteByte('\n')
+	}
+	return builder.String()
+}
+
+func agentEnvVar(agentID string, suffix ...string) string {
+	stem := strings.Trim(strings.Map(func(character rune) rune {
+		if character >= 'a' && character <= 'z' {
+			return character - ('a' - 'A')
+		}
+		if character >= 'A' && character <= 'Z' || character >= '0' && character <= '9' {
+			return character
+		}
+		return '_'
+	}, agentID), "_")
+	if len(suffix) == 0 {
+		return "ONEAGENT_API_KEY_" + stem
+	}
+	if suffix[0] == "API_BASE_URL" {
+		return "ONEAGENT_API_BASE_URL_" + stem
+	}
+	return "ONEAGENT_" + suffix[0] + "_" + stem
+}
diff --git a/internal/config/env_test.go b/internal/config/env_test.go
new file mode 100644
index 00000000..479d26bd
--- /dev/null
+++ b/internal/config/env_test.go
@@ -0,0 +1,54 @@
+package config
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+func TestWriteAgentEnvUsesDeclaredAndCompatibilityVariables(t *testing.T) {
+	home := t.TempDir()
+	path := filepath.Join(home, ".oneagent", "agents", "claude-code.env")
+	filesystem := securefs.New(securefs.Options{OS: "linux"})
+	if err := WriteAgentEnv(context.Background(), filesystem, path, "linux", "claude-code", "key'quoted", "https://api.example", "model-a", "model-fast", map[string]string{
+		"api_key": "ANTHROPIC_AUTH_TOKEN", "base_url": "ANTHROPIC_BASE_URL", "model": "ANTHROPIC_MODEL", "small_fast_model": "ANTHROPIC_SMALL_FAST_MODEL",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(data)
+	for _, expected := range []string{
+		"export ONEAGENT_API_KEY_CLAUDE_CODE='key'\\''quoted'",
+		"export ONEAGENT_API_BASE_URL_CLAUDE_CODE=https://api.example",
+		"export ONEAGENT_API_KEY='key'\\''quoted'",
+		"export ANTHROPIC_MODEL=model-a",
+		"export ANTHROPIC_SMALL_FAST_MODEL=model-fast",
+	} {
+		if !strings.Contains(text, expected) {
+			t.Fatalf("env missing %q: %s", expected, text)
+		}
+	}
+	if strings.Contains(text, "api_key") {
+		t.Fatal("env variable names unexpectedly contain internal field names")
+	}
+}
+
+func TestWriteAgentEnvWindowsAndSharedCompatibility(t *testing.T) {
+	home := t.TempDir()
+	filesystem := securefs.New(securefs.Options{OS: "windows", Username: "tester", Run: func(context.Context, []string) error { return nil }})
+	path := filepath.Join(home, ".oneagent", "env.ps1")
+	if err := WriteSharedEnv(context.Background(), filesystem, path, "windows", "key'quoted", "https://api.example"); err != nil {
+		t.Fatal(err)
+	}
+	data, _ := os.ReadFile(path)
+	if !strings.Contains(string(data), "$env:ONEAGENT_API_KEY = 'key''quoted'") || !strings.Contains(string(data), "$env:ONEAGENT_API_BASE_URL = 'https://api.example'") {
+		t.Fatalf("PowerShell env = %q", data)
+	}
+}
diff --git a/internal/config/testdata/parity/claude.golden b/internal/config/testdata/parity/claude.golden
new file mode 100644
index 00000000..04cda8a7
--- /dev/null
+++ b/internal/config/testdata/parity/claude.golden
@@ -0,0 +1,11 @@
+{
+  "keep": true,
+  "env": {
+    "CUSTOM": "value",
+    "ANTHROPIC_MODEL": "model-new",
+    "ANTHROPIC_BASE_URL": "https://api.ppio.com/anthropic",
+    "ANTHROPIC_AUTH_TOKEN": "sk-parity",
+    "ANTHROPIC_SMALL_FAST_MODEL": "model-new"
+  },
+  "other": true
+}
diff --git a/internal/config/testdata/parity/kilo.golden b/internal/config/testdata/parity/kilo.golden
new file mode 100644
index 00000000..5140ce50
--- /dev/null
+++ b/internal/config/testdata/parity/kilo.golden
@@ -0,0 +1,23 @@
+{
+  "provider": {
+    "other": {
+      "x": 1
+    },
+    "oneagent": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "PPIO",
+      "options": {
+        "baseURL": "https://api.ppio.com/openai/v1",
+        "apiKey": "{env:ONEAGENT_API_KEY_KILO_CLI}"
+      },
+      "models": {
+        "model-new": {
+          "name": "model-new"
+        }
+      }
+    }
+  },
+  "keep": true,
+  "$schema": "https://app.kilo.ai/config.json",
+  "model": "oneagent/model-new"
+}
diff --git a/internal/config/testdata/parity/opencode.golden b/internal/config/testdata/parity/opencode.golden
new file mode 100644
index 00000000..d64a1c4d
--- /dev/null
+++ b/internal/config/testdata/parity/opencode.golden
@@ -0,0 +1,24 @@
+{
+  "keep": true,
+  "provider": {
+    "other": {
+      "x": 1
+    },
+    "oneagent": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "PPIO",
+      "options": {
+        "baseURL": "https://api.ppio.com/openai/v1",
+        "apiKey": "{env:ONEAGENT_API_KEY_OPENCODE}"
+      },
+      "models": {
+        "model-new": {
+          "name": "model-new"
+        }
+      }
+    }
+  },
+  "theme": "dark",
+  "$schema": "https://opencode.ai/config.json",
+  "model": "oneagent/model-new"
+}
diff --git a/internal/config/write.go b/internal/config/write.go
new file mode 100644
index 00000000..5b4005f1
--- /dev/null
+++ b/internal/config/write.go
@@ -0,0 +1,246 @@
+package config
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"regexp"
+	"strconv"
+	"strings"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/jsonorder"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+	"github.com/pelletier/go-toml/v2"
+)
+
+type Writer struct {
+	Home string
+	OS   string
+	FS   securefs.Store
+}
+
+func NewWriter(home, osID string, filesystem securefs.Store) Writer {
+	return Writer{Home: home, OS: osID, FS: filesystem}
+}
+
+func (w Writer) WriteCodex(ctx context.Context, path, providerName, baseURL, model string) error {
+	managed := strings.Join([]string{
+		"model_provider = \"oneagent\"",
+		"model = " + quoteTOML(model),
+		"",
+		"[model_providers.oneagent]",
+		"name = " + quoteTOML(providerName),
+		"base_url = " + quoteTOML(baseURL),
+		"env_key = " + quoteTOML(agentEnvVar("codex")),
+		"wire_api = \"responses\"",
+		"",
+	}, "\n")
+	existing, err := readText(path)
+	if err != nil {
+		return configError("Cannot read existing TOML configuration %s: %v", path, err)
+	}
+	content, err := mergeCodexTOML(existing, managed, path)
+	if err != nil {
+		return err
+	}
+	return w.write(ctx, path, []byte(content), false)
+}
+
+func (w Writer) WriteClaude(ctx context.Context, path, baseURL, apiKey, model, smallFastModel string) error {
+	document, err := loadJSON(path)
+	if err != nil {
+		return err
+	}
+	env, err := document.Child("env")
+	if err != nil {
+		return configError("Existing Claude Code env configuration must contain an object: %s", path)
+	}
+	env.Set("ANTHROPIC_BASE_URL", baseURL)
+	env.Set("ANTHROPIC_AUTH_TOKEN", apiKey)
+	env.Set("ANTHROPIC_MODEL", model)
+	if smallFastModel == "" {
+		smallFastModel = model
+	}
+	env.Set("ANTHROPIC_SMALL_FAST_MODEL", smallFastModel)
+	return w.writeJSON(ctx, path, document, true)
+}
+
+func (w Writer) WriteOpenAICompatible(ctx context.Context, path, schemaURL, providerName, baseURL, model, agentID string) error {
+	document, err := loadJSON(path)
+	if err != nil {
+		return err
+	}
+	document.Set("$schema", schemaURL)
+	providers, err := document.Child("provider")
+	if err != nil {
+		return configError("Existing provider configuration must contain an object: %s", path)
+	}
+	options := jsonorder.NewObject()
+	options.Set("baseURL", provider.OpenAIBaseURL(baseURL))
+	options.Set("apiKey", "{env:"+agentEnvVar(agentID)+"}")
+	models := jsonorder.NewObject()
+	modelEntry := jsonorder.NewObject()
+	modelEntry.Set("name", model)
+	models.Set(model, modelEntry)
+	oneagent := jsonorder.NewObject()
+	oneagent.Set("npm", "@ai-sdk/openai-compatible")
+	oneagent.Set("name", providerName)
+	oneagent.Set("options", options)
+	oneagent.Set("models", models)
+	providers.Set("oneagent", oneagent)
+	document.Set("model", "oneagent/"+model)
+	return w.writeJSON(ctx, path, document, false)
+}
+
+func (w Writer) WriteAider(ctx context.Context, path, baseURL, apiKey string) error {
+	base := provider.OpenAIBaseURL(baseURL)
+	var content string
+	if w.OS == "windows" {
+		content = "$env:OPENAI_API_BASE = '" + powershellQuote(base) + "'\n" +
+			"$env:OPENAI_API_KEY = '" + powershellQuote(apiKey) + "'\n"
+	} else {
+		content = "export OPENAI_API_BASE=" + shellQuote(base) + "\n" +
+			"export OPENAI_API_KEY=" + shellQuote(apiKey) + "\n"
+	}
+	return w.write(ctx, path, []byte(content), true)
+}
+
+func (w Writer) write(ctx context.Context, path string, data []byte, secret bool) error {
+	if _, err := w.FS.AtomicWrite(ctx, path, data, secret); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (w Writer) writeJSON(ctx context.Context, path string, value *jsonorder.Object, secret bool) error {
+	data, err := jsonorder.Marshal(value)
+	if err != nil {
+		return configError("Cannot encode JSON configuration %s: %v", path, err)
+	}
+	return w.write(ctx, path, data, secret)
+}
+
+func readText(path string) (string, error) {
+	data, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return "", nil
+	}
+	if err != nil {
+		return "", err
+	}
+	return string(data), nil
+}
+
+func loadJSON(path string) (*jsonorder.Object, error) {
+	text, err := readText(path)
+	if err != nil {
+		return nil, configError("Cannot read existing JSON configuration %s: %v", path, err)
+	}
+	if strings.TrimSpace(text) == "" {
+		return jsonorder.NewObject(), nil
+	}
+	value, err := jsonorder.Parse([]byte(text))
+	if err != nil {
+		if strings.HasSuffix(path, ".jsonc") && jsoncCommentPattern.MatchString(text) {
+			return nil, configError("%s contains JSONC comments, which OneAgent cannot preserve when it rewrites the file", path)
+		}
+		return nil, configError("Existing JSON configuration is invalid: %s: %v", path, err)
+	}
+	return value, nil
+}
+
+func mergeCodexTOML(existing, managed, path string) (string, error) {
+	if strings.TrimSpace(existing) == "" {
+		return managed, nil
+	}
+	var parsed map[string]any
+	if err := toml.Unmarshal([]byte(existing), &parsed); err != nil {
+		return "", configError("Existing TOML configuration is invalid: %s: %v", path, err)
+	}
+	var topLevel, tables []string
+	removed := map[string]bool{}
+	managedFound := false
+	inTable := false
+	skipManaged := false
+	for line := range strings.SplitSeq(existing, "\n") {
+		stripped := strings.TrimSpace(line)
+		if strings.HasPrefix(stripped, "[") {
+			header := strings.ReplaceAll(strings.TrimSpace(strings.SplitN(stripped, "#", 2)[0]), " ", "")
+			inTable = true
+			skipManaged = managedSectionPattern.MatchString(header)
+			if skipManaged {
+				managedFound = true
+				continue
+			}
+		}
+		if skipManaged {
+			continue
+		}
+		if !inTable {
+			if match := topLevelKeyPattern.FindStringSubmatch(line); match != nil {
+				removed[match[1]] = true
+				continue
+			}
+			topLevel = append(topLevel, line)
+		} else {
+			tables = append(tables, line)
+		}
+	}
+	if providers, ok := parsed["model_providers"].(map[string]any); ok {
+		if _, exists := providers["oneagent"]; exists && !managedFound {
+			return "", configError("Unsupported OneAgent TOML table syntax in %s", path)
+		}
+	}
+	for _, key := range []string{"model_provider", "model"} {
+		if _, exists := parsed[key]; exists && !removed[key] {
+			return "", configError("Unsupported TOML key syntax for %s in %s", key, path)
+		}
+	}
+	sections := make([]string, 0, 3)
+	for _, section := range []string{strings.TrimSpace(strings.Join(topLevel, "\n")), strings.TrimSpace(managed), strings.TrimSpace(strings.Join(tables, "\n"))} {
+		if section != "" {
+			sections = append(sections, section)
+		}
+	}
+	merged := strings.Join(sections, "\n\n") + "\n"
+	var validation map[string]any
+	if err := toml.Unmarshal([]byte(merged), &validation); err != nil {
+		return "", configError("Cannot merge TOML configuration %s: %v", path, err)
+	}
+	return merged, nil
+}
+
+func quoteTOML(value string) string {
+	return strconv.Quote(value)
+}
+
+func shellQuote(value string) string {
+	if value != "" {
+		safe := true
+		for _, character := range value {
+			if !strings.ContainsRune("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_@%+=:,./-", character) {
+				safe = false
+				break
+			}
+		}
+		if safe {
+			return value
+		}
+	}
+	return "'" + strings.ReplaceAll(value, "'", "'\\''") + "'"
+}
+
+func powershellQuote(value string) string {
+	return strings.ReplaceAll(value, "'", "''")
+}
+
+func configError(format string, values ...any) error {
+	return oneerrors.New(oneerrors.ConfigWriteFailed, fmt.Sprintf(format, values...))
+}
+
+var (
+	topLevelKeyPattern    = regexp.MustCompile(`^\s*(model_provider|model)\s*=`)
+	managedSectionPattern = regexp.MustCompile(`^\[model_providers\.oneagent(?:\..+)?\]$`)
+)
diff --git a/internal/config/write_golden_test.go b/internal/config/write_golden_test.go
new file mode 100644
index 00000000..d80e91c9
--- /dev/null
+++ b/internal/config/write_golden_test.go
@@ -0,0 +1,68 @@
+package config
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+func TestJSONWritersMatchGoldenFiles(t *testing.T) {
+	cases := []struct {
+		kind     string
+		relative string
+		existing string
+	}{
+		{"claude", filepath.Join(".claude", "settings.json"), `{"keep":true,"env":{"CUSTOM":"value","ANTHROPIC_MODEL":"old"},"other":true}`},
+		{"opencode", filepath.Join(".config", "opencode", "opencode.jsonc"), `{"keep":true,"provider":{"other":{"x":1}},"theme":"dark"}`},
+		{"kilo", filepath.Join(".config", "kilo", "kilo.jsonc"), `{"provider":{"other":{"x":1}},"keep":true}`},
+	}
+
+	for _, testCase := range cases {
+		t.Run(testCase.kind, func(t *testing.T) {
+			want, err := os.ReadFile(filepath.Join("testdata", "parity", testCase.kind+".golden"))
+			if err != nil {
+				t.Fatal(err)
+			}
+			got := jsonWriterOutput(t, testCase.kind, testCase.relative, testCase.existing)
+			if string(got) != string(want) {
+				t.Fatalf("writer output differs from golden file:\ngot:\n%s\nwant:\n%s", got, want)
+			}
+		})
+	}
+}
+
+func jsonWriterOutput(t *testing.T, kind, relative, existing string) []byte {
+	t.Helper()
+	home := t.TempDir()
+	path := filepath.Join(home, relative)
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(existing), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	filesystem := securefs.New(securefs.Options{OS: "linux"})
+	writer := NewWriter(home, "linux", filesystem)
+	var err error
+	switch kind {
+	case "claude":
+		err = writer.WriteClaude(context.Background(), path, "https://api.ppio.com/anthropic", "sk-parity", "model-new", "")
+	case "opencode":
+		err = writer.WriteOpenAICompatible(context.Background(), path, "https://opencode.ai/config.json", "PPIO", "https://api.ppio.com/openai", "model-new", "opencode")
+	case "kilo":
+		err = writer.WriteOpenAICompatible(context.Background(), path, "https://app.kilo.ai/config.json", "PPIO", "https://api.ppio.com/openai", "model-new", "kilo-cli")
+	default:
+		t.Fatalf("unknown writer kind %q", kind)
+	}
+	if err != nil {
+		t.Fatal(err)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return data
+}
diff --git a/internal/config/write_test.go b/internal/config/write_test.go
new file mode 100644
index 00000000..39c966ef
--- /dev/null
+++ b/internal/config/write_test.go
@@ -0,0 +1,152 @@
+package config
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+func testWriter(t *testing.T, home, osID string) Writer {
+	t.Helper()
+	filesystem := securefs.New(securefs.Options{OS: osID})
+	return NewWriter(home, osID, filesystem)
+}
+
+func TestWriteCodexPreservesUnmanagedTablesAndRoundTrips(t *testing.T) {
+	home := t.TempDir()
+	path := filepath.Join(home, ".codex", "config.toml")
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte("approval_policy = \"on-request\"\nmodel_provider = \"old\"\nmodel = \"old-model\"\n\n[model_providers.old]\nname = \"Keep Me\"\n\n[model_providers.oneagent]\nname = \"Old\"\nbase_url = \"https://old.example\"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	writer := testWriter(t, home, "linux")
+	if err := writer.WriteCodex(context.Background(), path, "PPIO", "https://api.ppio.com/openai", "model-a"); err != nil {
+		t.Fatal(err)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(data)
+	if !strings.Contains(text, "approval_policy = \"on-request\"") || !strings.Contains(text, "name = \"Keep Me\"") || !strings.Contains(text, "model_provider = \"oneagent\"") {
+		t.Fatalf("merged Codex config = %s", text)
+	}
+	detected := ReadCodexConfig(text)
+	if detected.BaseURL != "https://api.ppio.com/openai" || detected.Model != "model-a" || !detected.ManagedByOneAgent || detected.Unreadable != nil {
+		t.Fatalf("round-trip Codex detection = %#v", detected)
+	}
+	for _, invalid := range []string{"model = \"unterminated\n", "[\"model_providers\".\"oneagent\"]\nname = \"quoted\"\n", "\"model\" = \"quoted\"\n"} {
+		if err := os.WriteFile(path, []byte(invalid), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := writer.WriteCodex(context.Background(), path, "PPIO", "https://example.com", "m"); err == nil {
+			t.Fatalf("invalid Codex config unexpectedly succeeded: %q", invalid)
+		}
+		got, _ := os.ReadFile(path)
+		if string(got) != invalid {
+			t.Fatalf("invalid Codex config was modified: %q", got)
+		}
+	}
+}
+
+func TestWriteJSONAdaptersPreserveFieldsAndRejectJSONC(t *testing.T) {
+	home := t.TempDir()
+	writer := testWriter(t, home, "linux")
+	claudePath := filepath.Join(home, ".claude", "settings.json")
+	if err := os.MkdirAll(filepath.Dir(claudePath), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(claudePath, []byte(`{"keep":true,"env":{ "CUSTOM":"value" }}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := writer.WriteClaude(context.Background(), claudePath, "https://anthropic.example", "sk-claude-secret", "model-a", ""); err != nil {
+		t.Fatal(err)
+	}
+	var claude map[string]any
+	data, _ := os.ReadFile(claudePath)
+	if err := json.Unmarshal(data, &claude); err != nil || claude["keep"] != true {
+		t.Fatalf("Claude config = %s, %v", data, err)
+	}
+	if got := string(data); !strings.Contains(got, "\"keep\": true,\n  \"env\":") {
+		t.Fatalf("Claude top-level key order changed: %s", data)
+	}
+	env := claude["env"].(map[string]any)
+	if env["ANTHROPIC_SMALL_FAST_MODEL"] != "model-a" || env["CUSTOM"] != "value" {
+		t.Fatalf("Claude env = %#v", env)
+	}
+	if got := string(data); !strings.Contains(got, "\"CUSTOM\": \"value\",\n    \"ANTHROPIC_BASE_URL\":") {
+		t.Fatalf("Claude nested key order changed: %s", data)
+	}
+	if !strings.Contains(string(data), "sk-claude-secret") {
+		t.Fatal("Claude config did not contain its required native credential")
+	}
+
+	openPath := filepath.Join(home, ".config", "opencode", "opencode.jsonc")
+	if err := os.MkdirAll(filepath.Dir(openPath), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(openPath, []byte(`{"keep":true,"provider":{"other":{"x":1}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := writer.WriteOpenAICompatible(context.Background(), openPath, "https://opencode.ai/config.json", "PPIO", "https://api.ppio.com/openai", "model-a", "opencode"); err != nil {
+		t.Fatal(err)
+	}
+	var open map[string]any
+	data, _ = os.ReadFile(openPath)
+	if err := json.Unmarshal(data, &open); err != nil || open["keep"] != true || open["model"] != "oneagent/model-a" {
+		t.Fatalf("OpenCode config = %s, %v", data, err)
+	}
+	if got := string(data); !strings.Contains(got, "\"keep\": true,\n  \"provider\":") || !strings.Contains(got, "\"provider\":") {
+		t.Fatalf("OpenCode top-level key order changed: %s", data)
+	}
+	providers := open["provider"].(map[string]any)
+	if _, ok := providers["other"]; !ok {
+		t.Fatalf("unmanaged provider removed: %#v", providers)
+	}
+	detected := ReadOpenAICompatibleConfig(string(data))
+	if detected.BaseURL != "https://api.ppio.com/openai/v1" || detected.Model != "model-a" || !detected.ManagedByOneAgent {
+		t.Fatalf("OpenCode round-trip = %#v", detected)
+	}
+
+	if err := os.WriteFile(openPath, []byte("{\n // keep\n \"theme\": \"dark\"\n}\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := writer.WriteOpenAICompatible(context.Background(), openPath, "schema", "PPIO", "https://api.ppio.com/openai", "m", "opencode"); err == nil || !strings.Contains(err.Error(), "JSONC comments") {
+		t.Fatalf("JSONC write error = %v", err)
+	}
+}
+
+func TestWriteAiderQuotesSecretsOnUnixAndWindows(t *testing.T) {
+	linuxHome := t.TempDir()
+	linux := testWriter(t, linuxHome, "linux")
+	linuxPath := filepath.Join(linuxHome, ".oneagent", "aider.env")
+	if err := linux.WriteAider(context.Background(), linuxPath, "https://api.example/openai", "key'quoted"); err != nil {
+		t.Fatal(err)
+	}
+	data, _ := os.ReadFile(linuxPath)
+	if !strings.Contains(string(data), "OPENAI_API_BASE=https://api.example/openai/v1") || !strings.Contains(string(data), "'key'\\''quoted'") {
+		t.Fatalf("Unix Aider config = %q", data)
+	}
+	if detected := ReadAiderConfig(string(data)); detected.BaseURL != "https://api.example/openai/v1" {
+		t.Fatalf("Unix Aider round-trip = %#v", detected)
+	}
+
+	windowsHome := t.TempDir()
+	filesystem := securefs.New(securefs.Options{OS: "windows", Username: "tester", Run: func(context.Context, []string) error { return nil }})
+	windows := NewWriter(windowsHome, "windows", filesystem)
+	windowsPath := filepath.Join(windowsHome, ".oneagent", "aider.ps1")
+	if err := windows.WriteAider(context.Background(), windowsPath, "https://api.example/openai", "key'quoted"); err != nil {
+		t.Fatal(err)
+	}
+	data, _ = os.ReadFile(windowsPath)
+	if !strings.Contains(string(data), "key''quoted") {
+		t.Fatalf("Windows Aider config = %q", data)
+	}
+}
diff --git a/internal/errors/errors.go b/internal/errors/errors.go
new file mode 100644
index 00000000..4b03c72c
--- /dev/null
+++ b/internal/errors/errors.go
@@ -0,0 +1,156 @@
+// Package oneerrors defines the stable error contract shared by the Go core,
+// Wails services, and the standalone CLI.
+package oneerrors
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+)
+
+const (
+	InvalidRequest      = "INVALID_REQUEST"
+	InvalidOrigin       = "INVALID_ORIGIN" // Retained for compatibility; HTTP is being removed.
+	PrerequisiteMissing = "PREREQUISITE_MISSING"
+	AgentInstallFailed  = "AGENT_INSTALL_FAILED"
+	ConfigWriteFailed   = "CONFIG_WRITE_FAILED"
+	APIKeyRejected      = "API_KEY_REJECTED"
+	ProviderUnreachable = "PROVIDER_UNREACHABLE"
+	ModelsUnsupported   = "MODELS_UNSUPPORTED"
+	ProtocolUnsupported = "PROTOCOL_UNSUPPORTED"
+	Timeout             = "TIMEOUT"
+	InternalError       = "INTERNAL_ERROR"
+)
+
+// ExitCodes is the stable process-level error contract. The map is copied by
+// callers when they need to expose it to a CLI parser.
+var ExitCodes = map[string]int{
+	InvalidRequest:      2,
+	InvalidOrigin:       2,
+	PrerequisiteMissing: 3,
+	AgentInstallFailed:  4,
+	ConfigWriteFailed:   5,
+	APIKeyRejected:      6,
+	ProviderUnreachable: 6,
+	ModelsUnsupported:   6,
+	ProtocolUnsupported: 7,
+	Timeout:             8,
+	InternalError:       10,
+}
+
+// OneAgentError is safe to serialize across the Wails bridge. Message must
+// already be free of credentials, file contents, and process output.
+type OneAgentError struct {
+	Code      string `json:"error_code"`
+	Message   string `json:"message"`
+	Status    int    `json:"status"`
+	Retryable bool   `json:"retryable"`
+	ExitCode  int    `json:"exit_code"`
+	cause     error
+}
+
+func New(code, message string, options ...Option) *OneAgentError {
+	err := &OneAgentError{
+		Code:     code,
+		Message:  message,
+		Status:   400,
+		ExitCode: ExitCodes[code],
+	}
+	if err.ExitCode == 0 {
+		err.Code = InternalError
+		err.ExitCode = ExitCodes[InternalError]
+	}
+	for _, option := range options {
+		option(err)
+	}
+	return err
+}
+
+// Option customizes an error without exposing mutable transport details.
+type Option func(*OneAgentError)
+
+func WithStatus(status int) Option {
+	return func(err *OneAgentError) { err.Status = status }
+}
+
+func WithRetryable(retryable bool) Option {
+	return func(err *OneAgentError) { err.Retryable = retryable }
+}
+
+func WithCause(cause error) Option {
+	return func(err *OneAgentError) { err.cause = cause }
+}
+
+func (e *OneAgentError) Error() string {
+	if e == nil {
+		return ""
+	}
+	return e.Message
+}
+
+func (e *OneAgentError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.cause
+}
+
+// APIShape preserves the current HTTP response fields while the transport is
+// being replaced by Wails bindings. It deliberately contains no cause or key.
+func (e *OneAgentError) APIShape() map[string]any {
+	if e == nil {
+		return map[string]any{
+			"ok":         false,
+			"error_code": InternalError,
+			"message":    "Unexpected OneAgent failure",
+			"error":      "Unexpected OneAgent failure",
+			"status":     500,
+			"retryable":  true,
+		}
+	}
+	return map[string]any{
+		"ok":         false,
+		"error":      e.Message,
+		"message":    e.Message,
+		"status":     e.Status,
+		"error_code": e.Code,
+		"retryable":  e.Retryable,
+	}
+}
+
+// MarshalJSON keeps the bridge payload restricted to the documented fields.
+func (e *OneAgentError) MarshalJSON() ([]byte, error) {
+	type wire struct {
+		Code      string `json:"error_code"`
+		Message   string `json:"message"`
+		Status    int    `json:"status"`
+		Retryable bool   `json:"retryable"`
+		ExitCode  int    `json:"exit_code"`
+	}
+	if e == nil {
+		return json.Marshal(wire{Code: InternalError, Message: "Unexpected OneAgent failure", Status: 500, Retryable: true, ExitCode: ExitCodes[InternalError]})
+	}
+	return json.Marshal(wire{Code: e.Code, Message: e.Message, Status: e.Status, Retryable: e.Retryable, ExitCode: e.ExitCode})
+}
+
+// As converts an arbitrary error to the stable transport type. Unknown errors
+// are intentionally generalized so internal details cannot reach the UI.
+func As(err error) *OneAgentError {
+	if err == nil {
+		return nil
+	}
+	if oneErr, ok := errors.AsType[*OneAgentError](err); ok {
+		return oneErr
+	}
+	return New(InternalError, "Unexpected OneAgent failure", WithStatus(500), WithRetryable(true), WithCause(err))
+}
+
+func Marshal(err error) []byte {
+	payload, marshalErr := json.Marshal(As(err))
+	if marshalErr != nil {
+		// The shape above only contains primitive values; this is a final guard
+		// for a Wails callback, which cannot return an error itself.
+		return fmt.Appendf(nil, `{"error_code":%q,"message":%q,"status":500,"retryable":true,"exit_code":10}`, InternalError, "Unexpected OneAgent failure")
+	}
+	return payload
+}
diff --git a/internal/errors/errors_test.go b/internal/errors/errors_test.go
new file mode 100644
index 00000000..546897a5
--- /dev/null
+++ b/internal/errors/errors_test.go
@@ -0,0 +1,42 @@
+package oneerrors
+
+import (
+	"encoding/json"
+	"errors"
+	"testing"
+)
+
+func TestStableErrorShapeAndExitCode(t *testing.T) {
+	err := New(ConfigWriteFailed, "configuration write failed", WithStatus(422), WithRetryable(true))
+	if err.ExitCode != 5 || err.Status != 422 || !err.Retryable {
+		t.Fatalf("unexpected error: %#v", err)
+	}
+	var wire map[string]any
+	if marshalErr := json.Unmarshal(Marshal(err), &wire); marshalErr != nil {
+		t.Fatal(marshalErr)
+	}
+	if wire["error_code"] != ConfigWriteFailed || wire["exit_code"] != float64(5) {
+		t.Fatalf("unexpected wire shape: %#v", wire)
+	}
+	if _, exists := wire["cause"]; exists {
+		t.Fatal("internal cause must not cross the bridge")
+	}
+}
+
+func TestAsGeneralizesUnknownErrors(t *testing.T) {
+	sentinel := errors.New("secret process output")
+	err := As(sentinel)
+	if err.Code != InternalError || err.ExitCode != 10 || !errors.Is(err, sentinel) {
+		t.Fatalf("unexpected generalized error: %#v", err)
+	}
+	if err.Message == sentinel.Error() {
+		t.Fatal("unknown error details leaked into the stable message")
+	}
+}
+
+func TestUnknownCodeFallsBackToInternal(t *testing.T) {
+	err := New("NOT_A_CODE", "ignored")
+	if err.Code != InternalError || err.ExitCode != ExitCodes[InternalError] {
+		t.Fatalf("unexpected fallback: %#v", err)
+	}
+}
diff --git a/internal/install/archive.go b/internal/install/archive.go
new file mode 100644
index 00000000..13b1f18f
--- /dev/null
+++ b/internal/install/archive.go
@@ -0,0 +1,190 @@
+package install
+
+import (
+	"archive/tar"
+	"archive/zip"
+	"compress/gzip"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// maxRuntimeEntryBytes bounds one extracted file. The largest entry in the
+// pinned artifacts is the node binary at roughly 120 MB, so this leaves room
+// while still refusing a decompression bomb.
+const maxRuntimeEntryBytes = 512 << 20
+
+// safeJoin resolves an archive entry inside destination and refuses anything
+// that escapes it. Archive members are untrusted input even when the archive
+// checksum matched: the checksum proves provenance, not that every path is
+// benign.
+func safeJoin(destination, name string) (string, error) {
+	if name == "" {
+		return "", fmt.Errorf("archive entry has an empty name")
+	}
+	cleaned := filepath.Clean(filepath.FromSlash(name))
+	if filepath.IsAbs(cleaned) || strings.HasPrefix(cleaned, ".."+string(os.PathSeparator)) || cleaned == ".." {
+		return "", fmt.Errorf("archive entry %q escapes the extraction directory", name)
+	}
+	if len(cleaned) > 1 && cleaned[1] == ':' {
+		return "", fmt.Errorf("archive entry %q contains a drive letter", name)
+	}
+	return filepath.Join(destination, cleaned), nil
+}
+
+func extractTarGz(archive, destination string) error {
+	file, err := os.Open(archive)
+	if err != nil {
+		return runtimeError("Cannot open the downloaded runtime archive", err)
+	}
+	defer file.Close()
+	decompressed, err := gzip.NewReader(file)
+	if err != nil {
+		return runtimeError("Cannot read the downloaded runtime archive", err)
+	}
+	defer decompressed.Close()
+
+	reader := tar.NewReader(decompressed)
+	for {
+		header, err := reader.Next()
+		if err == io.EOF {
+			return nil
+		}
+		if err != nil {
+			return runtimeError("Cannot read the downloaded runtime archive", err)
+		}
+		path, err := safeJoin(destination, header.Name)
+		if err != nil {
+			return runtimeError("The runtime archive contains an unsafe path", err)
+		}
+		switch header.Typeflag {
+		case tar.TypeDir:
+			if err := os.MkdirAll(path, 0o700); err != nil {
+				return runtimeError("Cannot create a runtime directory", err)
+			}
+		case tar.TypeReg:
+			if err := writeEntry(path, reader, header.FileInfo().Mode().Perm()); err != nil {
+				return err
+			}
+		case tar.TypeSymlink:
+			// node ships bin/npm and bin/npx as relative symlinks into
+			// lib/node_modules. Dropping them would leave the runtime without a
+			// package manager, so they are recreated after the same escape check.
+			if err := writeSymlink(destination, path, header.Linkname); err != nil {
+				return err
+			}
+		default:
+			// Hard links, devices and fifos are not part of any pinned artifact.
+			continue
+		}
+	}
+}
+
+func extractZip(archive, destination string) error {
+	reader, err := zip.OpenReader(archive)
+	if err != nil {
+		return runtimeError("Cannot read the downloaded runtime archive", err)
+	}
+	defer reader.Close()
+	for _, entry := range reader.File {
+		path, err := safeJoin(destination, entry.Name)
+		if err != nil {
+			return runtimeError("The runtime archive contains an unsafe path", err)
+		}
+		info := entry.FileInfo()
+		if info.IsDir() {
+			if err := os.MkdirAll(path, 0o700); err != nil {
+				return runtimeError("Cannot create a runtime directory", err)
+			}
+			continue
+		}
+		if info.Mode()&os.ModeSymlink != 0 {
+			target, err := readZipSymlink(entry)
+			if err != nil {
+				return runtimeError("Cannot read a runtime archive symlink", err)
+			}
+			if err := writeSymlink(destination, path, target); err != nil {
+				return err
+			}
+			continue
+		}
+		source, err := entry.Open()
+		if err != nil {
+			return runtimeError("Cannot read the downloaded runtime archive", err)
+		}
+		writeErr := writeEntry(path, source, info.Mode().Perm())
+		source.Close()
+		if writeErr != nil {
+			return writeErr
+		}
+	}
+	return nil
+}
+
+func readZipSymlink(entry *zip.File) (string, error) {
+	reader, err := entry.Open()
+	if err != nil {
+		return "", err
+	}
+	defer reader.Close()
+	target, err := io.ReadAll(io.LimitReader(reader, 4096))
+	if err != nil {
+		return "", err
+	}
+	return string(target), nil
+}
+
+func writeEntry(path string, source io.Reader, mode os.FileMode) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return runtimeError("Cannot create a runtime directory", err)
+	}
+	// The archive is a downloaded runtime, not a secret, but it lives under the
+	// user's private OneAgent directory: keep it owner-only and preserve only
+	// the executable bit the archive declared.
+	permissions := os.FileMode(0o600)
+	if mode&0o111 != 0 {
+		permissions = 0o700
+	}
+	file, err := os.OpenFile(path, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, permissions)
+	if err != nil {
+		return runtimeError("Cannot write a runtime file", err)
+	}
+	written, err := io.Copy(file, io.LimitReader(source, maxRuntimeEntryBytes+1))
+	closeErr := file.Close()
+	if err != nil {
+		return runtimeError("Cannot write a runtime file", err)
+	}
+	if closeErr != nil {
+		return runtimeError("Cannot write a runtime file", closeErr)
+	}
+	if written > maxRuntimeEntryBytes {
+		return runtimeError("A runtime archive entry exceeded the size limit", fmt.Errorf("%s is larger than %d bytes", filepath.Base(path), maxRuntimeEntryBytes))
+	}
+	return nil
+}
+
+func writeSymlink(destination, path, target string) error {
+	if target == "" {
+		return runtimeError("The runtime archive contains an unsafe path", fmt.Errorf("empty symlink target"))
+	}
+	// A symlink's target is checked as a path relative to the link's own
+	// directory: an entry pointing at ../../etc must not survive extraction.
+	resolved := target
+	if !filepath.IsAbs(filepath.FromSlash(target)) {
+		resolved = filepath.Join(filepath.Dir(path), filepath.FromSlash(target))
+	}
+	relative, err := filepath.Rel(destination, resolved)
+	if err != nil || relative == ".." || strings.HasPrefix(relative, ".."+string(os.PathSeparator)) {
+		return runtimeError("The runtime archive contains an unsafe path", fmt.Errorf("symlink %q escapes the extraction directory", target))
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return runtimeError("Cannot create a runtime directory", err)
+	}
+	_ = os.Remove(path)
+	if err := os.Symlink(filepath.FromSlash(target), path); err != nil {
+		return runtimeError("Cannot create a runtime symlink", err)
+	}
+	return nil
+}
diff --git a/internal/install/bootstrap.go b/internal/install/bootstrap.go
new file mode 100644
index 00000000..52134530
--- /dev/null
+++ b/internal/install/bootstrap.go
@@ -0,0 +1,374 @@
+package install
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+)
+
+// RuntimeDownloadTimeout bounds one runtime archive download. Node is roughly
+// 50 MB, so this is generous enough for a slow link but still terminates.
+const RuntimeDownloadTimeout = 10 * time.Minute
+
+// Doer is the narrow HTTP boundary so runtime downloads are testable without a
+// network. It matches internal/provider's client boundary on purpose.
+type Doer interface {
+	Do(*http.Request) (*http.Response, error)
+}
+
+// RuntimeState is the public projection of one managed runtime. It carries no
+// filesystem paths beyond the managed root so the UI cannot leak a private
+// directory layout it should not depend on.
+type RuntimeState struct {
+	ID             string `json:"id"`
+	Name           string `json:"name"`
+	Command        string `json:"command"`
+	Installed      bool   `json:"installed"`
+	Version        string `json:"version"`
+	LockedVersion  string `json:"lockedVersion"`
+	Managed        bool   `json:"managed"`
+	Supported      bool   `json:"supported"`
+	Note           string `json:"note"`
+	License        string `json:"license"`
+	LicenseURL     string `json:"licenseUrl"`
+	Source         string `json:"source"`
+	InstallPath    string `json:"installPath"`
+	RequiredByHint string `json:"requiredByHint,omitempty"`
+}
+
+// RuntimeRoot is the parent of every managed runtime tree.
+func RuntimeRoot(home string) string {
+	return filepath.Join(home, ".oneagent", "runtimes")
+}
+
+// runtimeDir is the versioned install directory. Keeping the version in the
+// path means a lock bump installs alongside the old tree instead of mutating a
+// directory a running Agent may be executing from.
+func runtimeDir(home, runtimeID, version string) string {
+	return filepath.Join(RuntimeRoot(home), runtimeID, "v"+version)
+}
+
+// ManagedBinDir returns the executable directory of an installed managed
+// runtime, or "" when this runtime is not installed under OneAgent's root.
+func ManagedBinDir(home string, runtimeID string, runtime catalog.Runtime, artifact catalog.RuntimeArtifact) string {
+	directory := runtimeDir(home, runtimeID, runtime.Version)
+	binDir := artifact.BinDir
+	if binDir == "" || binDir == "." {
+		binDir = ""
+	}
+	candidate := filepath.Join(directory, binDir)
+	if _, err := os.Stat(filepath.Join(candidate, ".oneagent-runtime-ok")); err != nil {
+		return ""
+	}
+	return candidate
+}
+
+// RuntimeStates reports every runtime in the lock file for the current
+// platform, including whether the command already resolves on this machine.
+func RuntimeStates(ctx context.Context, runtime Runtime, manifest catalog.RuntimeManifest) []RuntimeState {
+	key := catalog.RuntimeArtifactKey(runtime.Platform.OS, runtime.Platform.Arch)
+	states := make([]RuntimeState, 0, len(manifest.Runtimes))
+	for _, id := range manifest.RuntimeOrder {
+		entry := manifest.Runtimes[id]
+		artifact, supported := entry.Artifacts[key]
+		state := RuntimeState{
+			ID:            id,
+			Name:          entry.Name,
+			Command:       entry.ProbeCommand,
+			LockedVersion: entry.Version,
+			Supported:     supported,
+			Note:          entry.Note,
+			License:       entry.License,
+			LicenseURL:    entry.LicenseURL,
+			Source:        entry.Source,
+		}
+		if supported {
+			state.InstallPath = runtimeDir(runtime.Home, id, entry.Version)
+			state.Managed = ManagedBinDir(runtime.Home, id, entry, artifact) != ""
+		}
+		if executable, ok := lookRuntime(runtime, entry.ProbeCommand); ok {
+			state.Installed = true
+			state.Version = runtimeVersion(ctx, runtime, executable)
+		}
+		states = append(states, state)
+	}
+	return states
+}
+
+func lookRuntime(runtime Runtime, command string) (string, bool) {
+	if runtime.Runner == nil {
+		return "", false
+	}
+	executable, ok := runtime.Runner.LookPath(command)
+	if !ok || executable == "" {
+		return "", false
+	}
+	return executable, true
+}
+
+func runtimeVersion(ctx context.Context, runtime Runtime, executable string) string {
+	result, err := runtime.command(ctx, []string{executable, "--version"}, nil, VersionCommandTimeout)
+	if err != nil {
+		return ""
+	}
+	return VersionFromOutput(result.Stdout + "\n" + result.Stderr)
+}
+
+// RuntimeForCommand maps a package manager command to the runtime that
+// provides it, so a missing "npm" resolves to Node rather than to a runtime
+// named after the command.
+func RuntimeForCommand(manifest catalog.RuntimeManifest, command string) (string, catalog.Runtime, bool) {
+	for _, id := range manifest.RuntimeOrder {
+		entry := manifest.Runtimes[id]
+		for _, candidate := range entry.Commands {
+			if candidate == command {
+				return id, entry, true
+			}
+		}
+	}
+	return "", catalog.Runtime{}, false
+}
+
+// EnsureRuntime installs a locked runtime when its command is not already
+// resolvable, and returns the runtime with the executable directory prepended
+// to its PATH. An already-satisfied runtime is a no-op: the command resolving
+// on the host is enough, whether it came from OneAgent or the user's own
+// installation.
+func EnsureRuntime(ctx context.Context, runtime Runtime, client Doer, runtimeID string, entry catalog.Runtime) (Runtime, bool, error) {
+	if err := checkContext(ctx); err != nil {
+		return runtime, false, err
+	}
+	key := catalog.RuntimeArtifactKey(runtime.Platform.OS, runtime.Platform.Arch)
+	artifact, supported := entry.Artifacts[key]
+	if !supported {
+		return runtime, false, prerequisiteError(fmt.Sprintf("%s has no locked download for %s", entry.Name, key))
+	}
+	// A managed tree from an earlier run only needs to be put back on PATH.
+	if binDir := ManagedBinDir(runtime.Home, runtimeID, entry, artifact); binDir != "" {
+		return withPath(runtime, binDir), false, nil
+	}
+	if _, ok := lookRuntime(runtime, entry.ProbeCommand); ok {
+		return runtime, false, nil
+	}
+	binDir, err := installRuntime(ctx, runtime, client, runtimeID, entry, artifact)
+	if err != nil {
+		return runtime, false, err
+	}
+	return withPath(runtime, binDir), true, nil
+}
+
+// WithManagedPath returns a copy of the runtime whose environment and command
+// lookup both resolve binDir first. Callers that run npm or uv use it so a
+// runtime installed by OneAgent is found the same way a system one would be.
+func WithManagedPath(runtime Runtime, binDir string) Runtime {
+	return withPath(runtime, binDir)
+}
+
+// withPath returns a copy of the runtime whose environment resolves the managed
+// directory first. Env is cloned because Runtime is passed by value but its map
+// is shared.
+func withPath(runtime Runtime, binDir string) Runtime {
+	if binDir == "" {
+		return runtime
+	}
+	environment := cloneEnv(runtime.Env)
+	key := "PATH"
+	if runtime.Platform.OS == "windows" {
+		for name := range environment {
+			if strings.EqualFold(name, "PATH") {
+				key = name
+				break
+			}
+		}
+	}
+	current := environment[key]
+	if current == "" || !hasPathEntry(current, binDir) {
+		if current == "" {
+			environment[key] = binDir
+		} else {
+			environment[key] = binDir + string(os.PathListSeparator) + current
+		}
+	}
+	runtime.Env = environment
+	if osRunner, ok := runtime.Runner.(process.OSRunner); ok && osRunner.Lookup == nil {
+		osRunner.Env = environment
+		runtime.Runner = osRunner
+	}
+	return runtime
+}
+
+func hasPathEntry(search, directory string) bool {
+	for _, entry := range filepath.SplitList(search) {
+		if entry == directory {
+			return true
+		}
+	}
+	return false
+}
+
+func installRuntime(ctx context.Context, runtime Runtime, client Doer, runtimeID string, entry catalog.Runtime, artifact catalog.RuntimeArtifact) (string, error) {
+	target := runtimeDir(runtime.Home, runtimeID, entry.Version)
+	parent := filepath.Dir(target)
+	if err := os.MkdirAll(parent, 0o700); err != nil {
+		return "", runtimeError(fmt.Sprintf("Cannot create the runtime directory for %s", entry.Name), err)
+	}
+	if runtime.OnOutput != nil {
+		runtime.OnOutput(process.Output{Kind: "command", Args: []string{"oneagent", "install-runtime", runtimeID, entry.Version}})
+	}
+	archive, err := downloadArtifact(ctx, runtime, client, entry, artifact, parent)
+	if err != nil {
+		return "", err
+	}
+	defer os.Remove(archive)
+
+	// Extract beside the final directory so a partial or corrupt tree is never
+	// visible under the versioned path, then swap it in with one rename.
+	staging, err := os.MkdirTemp(parent, ".staging-")
+	if err != nil {
+		return "", runtimeError(fmt.Sprintf("Cannot stage the %s installation", entry.Name), err)
+	}
+	defer os.RemoveAll(staging)
+	if err := extract(archive, staging, artifact); err != nil {
+		return "", err
+	}
+	root := staging
+	if artifact.StripRoot {
+		if root, err = singleChild(staging); err != nil {
+			return "", runtimeError(fmt.Sprintf("The %s archive layout is unexpected", entry.Name), err)
+		}
+	}
+	binDir := root
+	if artifact.BinDir != "" && artifact.BinDir != "." {
+		binDir = filepath.Join(root, artifact.BinDir)
+	}
+	if _, err := os.Stat(binDir); err != nil {
+		return "", runtimeError(fmt.Sprintf("The %s archive has no %s directory", entry.Name, artifact.BinDir), err)
+	}
+	// The marker is written before the rename so it lands atomically with the
+	// tree. Its presence is what makes a directory count as a managed install.
+	if err := os.WriteFile(filepath.Join(binDir, ".oneagent-runtime-ok"), []byte(entry.Version+"\n"), 0o600); err != nil {
+		return "", runtimeError(fmt.Sprintf("Cannot finalize the %s installation", entry.Name), err)
+	}
+	if err := os.RemoveAll(target); err != nil {
+		return "", runtimeError(fmt.Sprintf("Cannot replace the existing %s directory", entry.Name), err)
+	}
+	if err := os.Rename(root, target); err != nil {
+		return "", runtimeError(fmt.Sprintf("Cannot publish the %s installation", entry.Name), err)
+	}
+	installed := target
+	if artifact.BinDir != "" && artifact.BinDir != "." {
+		installed = filepath.Join(target, artifact.BinDir)
+	}
+	return installed, nil
+}
+
+func downloadArtifact(ctx context.Context, runtime Runtime, client Doer, entry catalog.Runtime, artifact catalog.RuntimeArtifact, directory string) (string, error) {
+	if client == nil {
+		client = &http.Client{Timeout: RuntimeDownloadTimeout}
+	}
+	downloadCtx, cancel := context.WithTimeout(ctx, RuntimeDownloadTimeout)
+	defer cancel()
+
+	sources := []string{artifact.URL}
+	// A mirror is only a transport fallback. It must satisfy the same locked
+	// checksum, so a hostile mirror cannot substitute a different archive.
+	if artifact.MirrorURL != "" && preferMirror(runtime.Env) {
+		sources = []string{artifact.MirrorURL, artifact.URL}
+	} else if artifact.MirrorURL != "" {
+		sources = append(sources, artifact.MirrorURL)
+	}
+	var lastErr error
+	for _, source := range sources {
+		path, err := fetchTo(downloadCtx, client, source, artifact.SHA256, directory)
+		if err == nil {
+			return path, nil
+		}
+		lastErr = err
+	}
+	return "", runtimeError(fmt.Sprintf("Cannot download %s %s", entry.Name, entry.Version), lastErr)
+}
+
+// preferMirror honors an explicit mirror preference only. There is no locale or
+// IP sniffing: an unexpected default download host would be surprising.
+func preferMirror(environment map[string]string) bool {
+	value := strings.ToLower(strings.TrimSpace(environment["ONEAGENT_RUNTIME_MIRROR"]))
+	return value == "1" || value == "true" || value == "npmmirror"
+}
+
+func fetchTo(ctx context.Context, client Doer, source, expected, directory string) (string, error) {
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, source, nil)
+	if err != nil {
+		return "", err
+	}
+	response, err := client.Do(request)
+	if err != nil {
+		return "", err
+	}
+	defer response.Body.Close()
+	if response.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("download returned HTTP %d", response.StatusCode)
+	}
+	file, err := os.CreateTemp(directory, ".download-")
+	if err != nil {
+		return "", err
+	}
+	path := file.Name()
+	digest := sha256.New()
+	_, copyErr := io.Copy(io.MultiWriter(file, digest), response.Body)
+	closeErr := file.Close()
+	if copyErr != nil || closeErr != nil {
+		os.Remove(path)
+		if copyErr != nil {
+			return "", copyErr
+		}
+		return "", closeErr
+	}
+	if actual := hex.EncodeToString(digest.Sum(nil)); actual != expected {
+		os.Remove(path)
+		return "", fmt.Errorf("checksum mismatch: lock expects %s, download reports %s", expected, actual)
+	}
+	return path, nil
+}
+
+func extract(archive, destination string, artifact catalog.RuntimeArtifact) error {
+	switch artifact.Archive {
+	case "tar.gz":
+		return extractTarGz(archive, destination)
+	case "zip":
+		return extractZip(archive, destination)
+	default:
+		return prerequisiteError("Unsupported runtime archive format: " + artifact.Archive)
+	}
+}
+
+func singleChild(directory string) (string, error) {
+	entries, err := os.ReadDir(directory)
+	if err != nil {
+		return "", err
+	}
+	directories := make([]string, 0, 1)
+	for _, entry := range entries {
+		if entry.IsDir() {
+			directories = append(directories, entry.Name())
+		}
+	}
+	if len(directories) != 1 {
+		return "", fmt.Errorf("expected exactly one top-level directory, found %d", len(directories))
+	}
+	return filepath.Join(directory, directories[0]), nil
+}
+
+func runtimeError(message string, cause error) error {
+	return oneerrors.New(oneerrors.AgentInstallFailed, message, oneerrors.WithRetryable(true), oneerrors.WithCause(cause))
+}
diff --git a/internal/install/bootstrap_test.go b/internal/install/bootstrap_test.go
new file mode 100644
index 00000000..683b5c44
--- /dev/null
+++ b/internal/install/bootstrap_test.go
@@ -0,0 +1,337 @@
+package install
+
+import (
+	"archive/tar"
+	"archive/zip"
+	"bytes"
+	"compress/gzip"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+type fakeDownloader struct {
+	bodies map[string][]byte
+	hits   []string
+}
+
+func (d *fakeDownloader) Do(request *http.Request) (*http.Response, error) {
+	url := request.URL.String()
+	d.hits = append(d.hits, url)
+	body, ok := d.bodies[url]
+	if !ok {
+		return &http.Response{StatusCode: http.StatusNotFound, Body: io.NopCloser(strings.NewReader("")), Request: request}, nil
+	}
+	return &http.Response{StatusCode: http.StatusOK, Body: io.NopCloser(bytes.NewReader(body)), Request: request}, nil
+}
+
+// tarball builds a node-shaped archive: a single root directory, a bin/ payload
+// and the relative bin/npm symlink node actually ships.
+func tarball(t *testing.T, root string) []byte {
+	t.Helper()
+	buffer := &bytes.Buffer{}
+	compressor := gzip.NewWriter(buffer)
+	writer := tar.NewWriter(compressor)
+	write := func(header *tar.Header, content string) {
+		if err := writer.WriteHeader(header); err != nil {
+			t.Fatal(err)
+		}
+		if content != "" {
+			if _, err := writer.Write([]byte(content)); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+	write(&tar.Header{Name: root + "/", Typeflag: tar.TypeDir, Mode: 0o755}, "")
+	write(&tar.Header{Name: root + "/bin/", Typeflag: tar.TypeDir, Mode: 0o755}, "")
+	// node ships npm-cli.js executable; bin/npm is a symlink to it, so the mode
+	// on the target is what makes the resolved npm runnable.
+	write(&tar.Header{Name: root + "/lib/npm-cli.js", Typeflag: tar.TypeReg, Mode: 0o755, Size: 3}, "cli")
+	write(&tar.Header{Name: root + "/bin/node", Typeflag: tar.TypeReg, Mode: 0o755, Size: 4}, "node")
+	write(&tar.Header{Name: root + "/bin/npm", Typeflag: tar.TypeSymlink, Linkname: "../lib/npm-cli.js", Mode: 0o777}, "")
+	if err := writer.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := compressor.Close(); err != nil {
+		t.Fatal(err)
+	}
+	return buffer.Bytes()
+}
+
+// zipball builds a uv-shaped archive: flat executables, no root directory.
+func zipball(t *testing.T, names ...string) []byte {
+	t.Helper()
+	buffer := &bytes.Buffer{}
+	writer := zip.NewWriter(buffer)
+	for _, name := range names {
+		header := &zip.FileHeader{Name: name, Method: zip.Deflate}
+		header.SetMode(0o755)
+		entry, err := writer.CreateHeader(header)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, err := entry.Write([]byte("binary")); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := writer.Close(); err != nil {
+		t.Fatal(err)
+	}
+	return buffer.Bytes()
+}
+
+func digestOf(data []byte) string {
+	sum := sha256.Sum256(data)
+	return hex.EncodeToString(sum[:])
+}
+
+func bootstrapRuntime(t *testing.T, home, osID string) Runtime {
+	t.Helper()
+	runner := process.New(map[string]string{"HOME": home, "PATH": filepath.Join(home, "empty")})
+	return NewRuntime(home, platform.For(osID, "arm64"), runner, runner.Env)
+}
+
+func TestEnsureRuntimeInstallsVerifiesAndExposesOnPath(t *testing.T) {
+	home := t.TempDir()
+	archive := tarball(t, "node-v1.2.3-darwin-arm64")
+	downloader := &fakeDownloader{bodies: map[string][]byte{"https://example.test/node.tar.gz": archive}}
+	entry := catalog.Runtime{
+		Name: "Node.js", Version: "1.2.3", Commands: []string{"node", "npm"}, ProbeCommand: "npm",
+		Artifacts: map[string]catalog.RuntimeArtifact{
+			"macos-arm64": {URL: "https://example.test/node.tar.gz", SHA256: digestOf(archive), Archive: "tar.gz", StripRoot: true, BinDir: "bin"},
+		},
+	}
+	runtime := bootstrapRuntime(t, home, "darwin")
+
+	updated, installed, err := EnsureRuntime(context.Background(), runtime, downloader, "node", entry)
+	if err != nil || !installed {
+		t.Fatalf("install = %v, %v", installed, err)
+	}
+	binDir := filepath.Join(RuntimeRoot(home), "node", "v1.2.3", "bin")
+	if _, err := os.Stat(filepath.Join(binDir, "node")); err != nil {
+		t.Fatalf("node binary missing: %v", err)
+	}
+	// node's bin/npm is a symlink into lib/. Losing it would leave the runtime
+	// installed but with no package manager.
+	target, err := os.Readlink(filepath.Join(binDir, "npm"))
+	if err != nil || target != filepath.FromSlash("../lib/npm-cli.js") {
+		t.Fatalf("npm symlink = %q, %v", target, err)
+	}
+	if !hasPathEntry(updated.Env["PATH"], binDir) {
+		t.Fatalf("managed bin dir is not on PATH: %q", updated.Env["PATH"])
+	}
+	// The runner must resolve through the updated PATH, otherwise the installer
+	// reports npm as missing right after installing it.
+	if resolved, ok := updated.Runner.LookPath("npm"); !ok || filepath.Dir(resolved) != binDir {
+		t.Fatalf("npm lookup = %q, %v", resolved, ok)
+	}
+
+	// A second call is a no-op that only re-exposes the existing tree.
+	before := len(downloader.hits)
+	again, installedAgain, err := EnsureRuntime(context.Background(), bootstrapRuntime(t, home, "darwin"), downloader, "node", entry)
+	if err != nil || installedAgain {
+		t.Fatalf("second install = %v, %v", installedAgain, err)
+	}
+	if len(downloader.hits) != before {
+		t.Fatalf("second call downloaded again: %v", downloader.hits)
+	}
+	if !hasPathEntry(again.Env["PATH"], binDir) {
+		t.Fatalf("second call lost the managed PATH entry: %q", again.Env["PATH"])
+	}
+}
+
+func TestEnsureRuntimeRejectsChecksumMismatchAndKeepsNothing(t *testing.T) {
+	home := t.TempDir()
+	archive := tarball(t, "node-v1.2.3-darwin-arm64")
+	downloader := &fakeDownloader{bodies: map[string][]byte{"https://example.test/node.tar.gz": archive}}
+	entry := catalog.Runtime{
+		Name: "Node.js", Version: "1.2.3", Commands: []string{"npm"}, ProbeCommand: "npm",
+		Artifacts: map[string]catalog.RuntimeArtifact{
+			"macos-arm64": {URL: "https://example.test/node.tar.gz", SHA256: strings.Repeat("a", 64), Archive: "tar.gz", StripRoot: true, BinDir: "bin"},
+		},
+	}
+	_, _, err := EnsureRuntime(context.Background(), bootstrapRuntime(t, home, "darwin"), downloader, "node", entry)
+	if err == nil || oneerrors.As(err).Code != oneerrors.AgentInstallFailed {
+		t.Fatalf("checksum mismatch error = %v", err)
+	}
+	if _, statErr := os.Stat(filepath.Join(RuntimeRoot(home), "node", "v1.2.3")); !os.IsNotExist(statErr) {
+		t.Fatalf("a rejected download left a runtime directory behind")
+	}
+}
+
+func TestEnsureRuntimeSupportsFlatZipAndSkipsExistingCommand(t *testing.T) {
+	home := t.TempDir()
+	archive := zipball(t, "uv.exe", "uvx.exe")
+	downloader := &fakeDownloader{bodies: map[string][]byte{"https://example.test/uv.zip": archive}}
+	entry := catalog.Runtime{
+		Name: "uv", Version: "0.1.0", Commands: []string{"uv"}, ProbeCommand: "uv",
+		Artifacts: map[string]catalog.RuntimeArtifact{
+			"windows-arm64": {URL: "https://example.test/uv.zip", SHA256: digestOf(archive), Archive: "zip", StripRoot: false, BinDir: "."},
+		},
+	}
+	updated, installed, err := EnsureRuntime(context.Background(), bootstrapRuntime(t, home, "windows"), downloader, "uv", entry)
+	if err != nil || !installed {
+		t.Fatalf("zip install = %v, %v", installed, err)
+	}
+	if _, statErr := os.Stat(filepath.Join(RuntimeRoot(home), "uv", "v0.1.0", "uv.exe")); statErr != nil {
+		t.Fatalf("uv.exe missing: %v", statErr)
+	}
+	if !hasPathEntry(updated.Env["PATH"], filepath.Join(RuntimeRoot(home), "uv", "v0.1.0")) {
+		t.Fatalf("uv directory is not on PATH: %q", updated.Env["PATH"])
+	}
+
+	// A host that already provides the command is left untouched: OneAgent does
+	// not replace a user's own installation.
+	existing := Runtime{Home: t.TempDir(), Platform: platform.For("windows", "arm64"), Env: map[string]string{}, Runner: &fakeInstallRunner{paths: map[string]string{"uv": "C:\\tools\\uv.exe"}}}
+	_, installedAgain, err := EnsureRuntime(context.Background(), existing, downloader, "uv", entry)
+	if err != nil || installedAgain {
+		t.Fatalf("existing uv should not be reinstalled: %v, %v", installedAgain, err)
+	}
+}
+
+func TestExtractRefusesEscapingPaths(t *testing.T) {
+	destination := t.TempDir()
+	buffer := &bytes.Buffer{}
+	compressor := gzip.NewWriter(buffer)
+	writer := tar.NewWriter(compressor)
+	if err := writer.WriteHeader(&tar.Header{Name: "../escaped", Typeflag: tar.TypeReg, Mode: 0o644, Size: 3}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := writer.Write([]byte("bad")); err != nil {
+		t.Fatal(err)
+	}
+	writer.Close()
+	compressor.Close()
+	archive := filepath.Join(t.TempDir(), "evil.tar.gz")
+	if err := os.WriteFile(archive, buffer.Bytes(), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := extractTarGz(archive, destination); err == nil {
+		t.Fatal("a traversal entry was accepted")
+	}
+
+	// A symlink whose target escapes must be refused even though its own name
+	// resolves inside the destination.
+	if err := writeSymlink(destination, filepath.Join(destination, "link"), "../../etc/passwd"); err == nil {
+		t.Fatal("an escaping symlink was accepted")
+	}
+}
+
+func TestPersistRuntimePathIsIdempotentAndGuardsDuplicates(t *testing.T) {
+	home := t.TempDir()
+	profile := filepath.Join(home, ".zshrc")
+	if err := os.WriteFile(profile, []byte("export EDITOR=vi\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	runtime := bootstrapRuntime(t, home, "darwin")
+	filesystem := securefs.New(securefs.Options{OS: "macos"})
+	binDir := filepath.Join(RuntimeRoot(home), "node", "v1.2.3", "bin")
+
+	changed, err := PersistRuntimePath(context.Background(), runtime, filesystem, []string{binDir})
+	if err != nil || !changed {
+		t.Fatalf("first persist = %v, %v", changed, err)
+	}
+	first, err := os.ReadFile(profile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(first), "export EDITOR=vi") {
+		t.Fatalf("persist dropped existing profile content: %q", first)
+	}
+	script, err := os.ReadFile(filepath.Join(RuntimeRoot(home), envScriptName))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(script), binDir) {
+		t.Fatalf("script does not export the managed directory: %q", script)
+	}
+	// The generated script must not grow PATH when it is sourced twice.
+	if !strings.Contains(string(script), `case ":$PATH:" in`) {
+		t.Fatalf("script has no duplicate guard: %q", script)
+	}
+
+	changed, err = PersistRuntimePath(context.Background(), runtime, filesystem, []string{binDir})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if changed {
+		t.Fatal("a second persist rewrote an unchanged profile")
+	}
+	second, err := os.ReadFile(profile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Count(string(second), pathMarkerBegin) != 1 {
+		t.Fatalf("profile has duplicate OneAgent blocks: %q", second)
+	}
+
+	// A version bump replaces the block instead of appending a second one.
+	next := filepath.Join(RuntimeRoot(home), "node", "v2.0.0", "bin")
+	if _, err := PersistRuntimePath(context.Background(), runtime, filesystem, []string{next}); err != nil {
+		t.Fatal(err)
+	}
+	third, err := os.ReadFile(profile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Count(string(third), pathMarkerBegin) != 1 {
+		t.Fatalf("version bump duplicated the block: %q", third)
+	}
+	updatedScript, err := os.ReadFile(filepath.Join(RuntimeRoot(home), envScriptName))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(updatedScript), binDir) {
+		t.Fatalf("script still references the superseded directory: %q", updatedScript)
+	}
+}
+
+func TestRuntimeLockCoversEveryDesktopPlatform(t *testing.T) {
+	manifest, err := catalog.LoadEmbeddedRuntimes()
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, id := range []string{"node", "uv"} {
+		entry, present := manifest.Runtimes[id]
+		if !present {
+			t.Fatalf("runtime lock is missing %s", id)
+		}
+		for _, osID := range []string{"macos", "windows", "linux"} {
+			for _, arch := range []string{"x64", "arm64"} {
+				key := catalog.RuntimeArtifactKey(osID, arch)
+				if _, ok := entry.Artifacts[key]; !ok {
+					t.Fatalf("%s has no locked artifact for %s", id, key)
+				}
+			}
+		}
+	}
+}
+
+func TestRuntimeForCommandMapsPackageManagers(t *testing.T) {
+	manifest, err := catalog.LoadEmbeddedRuntimes()
+	if err != nil {
+		t.Fatal(err)
+	}
+	// npm must resolve to node, not to a runtime named after the command.
+	if id, _, ok := RuntimeForCommand(manifest, "npm"); !ok || id != "node" {
+		t.Fatalf("npm maps to %q, %v", id, ok)
+	}
+	if id, _, ok := RuntimeForCommand(manifest, "uv"); !ok || id != "uv" {
+		t.Fatalf("uv maps to %q, %v", id, ok)
+	}
+	if _, _, ok := RuntimeForCommand(manifest, "pip"); ok {
+		t.Fatal("pip should not resolve to a bootstrappable runtime")
+	}
+}
diff --git a/internal/install/install.go b/internal/install/install.go
new file mode 100644
index 00000000..6c4404fb
--- /dev/null
+++ b/internal/install/install.go
@@ -0,0 +1,402 @@
+package install
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/url"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+)
+
+type Options struct {
+	EnforceLocked bool
+	Latest        bool
+	Timeout       time.Duration
+	Registry      string
+}
+
+type Result struct {
+	Installed     bool
+	Version       string
+	LockedVersion string
+	Registry      string
+}
+
+var versionPattern = regexp.MustCompile(`(^|[^0-9])([0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.+-]+)?)`)
+
+func VersionFromOutput(text string) string {
+	match := versionPattern.FindStringSubmatch(text)
+	if len(match) == 0 {
+		return ""
+	}
+	return match[2]
+}
+
+func InstalledVersion(ctx context.Context, runtime Runtime, agent catalog.Agent) string {
+	if agent.Command == "" || runtime.Runner == nil {
+		return ""
+	}
+	executable, ok := runtime.Runner.LookPath(agent.Command)
+	if !ok || executable == "" {
+		return ""
+	}
+	args := append([]string{executable}, agent.VersionArgs...)
+	if len(agent.VersionArgs) == 0 {
+		args = append(args, "--version")
+	}
+	result, err := runtime.command(ctx, args, nil, VersionCommandTimeout)
+	if err != nil {
+		return ""
+	}
+	return VersionFromOutput(result.Stdout + "\n" + result.Stderr)
+}
+
+// AiderPythonVersion is the interpreter Aider is pinned against. It is passed
+// to uv as a request, not as a path: uv reuses a matching system interpreter
+// when one exists and downloads a managed one when it does not.
+const AiderPythonVersion = "3.12"
+
+// managedNPM reports whether this npm came from OneAgent's runtime root.
+func managedNPM(runtime Runtime, npm string) bool {
+	if npm == "" {
+		return false
+	}
+	root := RuntimeRoot(runtime.Home)
+	relative, err := filepath.Rel(root, npm)
+	return err == nil && relative != ".." && !strings.HasPrefix(relative, ".."+string(filepath.Separator))
+}
+
+// ResolveAiderPython312 reports an existing Python 3.12 when the host has one.
+// It is retained for the CLI's diagnostics; installation itself no longer needs
+// it because uv provisions the interpreter.
+func ResolveAiderPython312(ctx context.Context, runtime Runtime) (string, error) {
+	if err := checkContext(ctx); err != nil {
+		return "", err
+	}
+	if runtime.Runner == nil {
+		return "", prerequisiteError("An existing Python 3.12 installation is required for Aider; OneAgent will not download Python automatically")
+	}
+	if executable, ok := runtime.Runner.LookPath("python3.12"); ok && executable != "" {
+		return executable, nil
+	}
+	for _, command := range []string{"python3", "python"} {
+		executable, ok := runtime.Runner.LookPath(command)
+		if !ok || executable == "" {
+			continue
+		}
+		result, err := runtime.command(ctx, []string{executable, "--version"}, nil, VersionCommandTimeout)
+		if err != nil || result.ExitCode != 0 {
+			if isContextError(err) {
+				return "", timeoutError("Checking for Python 3.12 was cancelled", err)
+			}
+			continue
+		}
+		version := VersionFromOutput(result.Stdout + "\n" + result.Stderr)
+		if strings.HasPrefix(version, "3.12.") {
+			return executable, nil
+		}
+	}
+	if runtime.Platform.OS == "windows" {
+		if launcher, ok := runtime.Runner.LookPath("py"); ok && launcher != "" {
+			result, err := runtime.command(ctx, []string{launcher, "-3.12", "--version"}, nil, VersionCommandTimeout)
+			if err != nil {
+				if isContextError(err) {
+					return "", timeoutError("Checking for Python 3.12 was cancelled", err)
+				}
+			} else if result.ExitCode == 0 {
+				return "3.12", nil
+			}
+		}
+	}
+	return "", prerequisiteError("An existing Python 3.12 installation is required for Aider; OneAgent will not download Python automatically")
+}
+
+func ResolveRegistry(value string) (string, error) {
+	official := officialRegistry()
+	if value == "" {
+		return official, nil
+	}
+	for _, mirror := range catalog.Mirrors() {
+		if value == mirror.ID {
+			return mirror.Registry, nil
+		}
+	}
+	for _, character := range value {
+		if character < 32 || character == 127 {
+			return "", oneerrors.New(oneerrors.InvalidRequest, "Registry URL contains control characters")
+		}
+	}
+	parsed, err := url.Parse(value)
+	if err != nil || parsed.Scheme != "https" || parsed.Host == "" {
+		return "", oneerrors.New(oneerrors.InvalidRequest, "Registry URL must start with https://")
+	}
+	if parsed.User != nil {
+		return "", oneerrors.New(oneerrors.InvalidRequest, "Registry URL must not contain credentials")
+	}
+	return strings.TrimRight(value, "/") + "/", nil
+}
+
+func VerifyNPMIntegrity(ctx context.Context, runtime Runtime, npm, spec, expected, registry string, timeout time.Duration) error {
+	if expected == "" {
+		return nil
+	}
+	result, err := runtime.command(ctx, []string{npm, "view", spec, "dist.integrity", "--registry=" + registry}, nil, runtime.timeout(timeout))
+	if err != nil {
+		if isContextError(err) {
+			return oneerrors.New(oneerrors.AgentInstallFailed, "Timed out reading the checksum for "+spec, oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+		}
+		return oneerrors.New(oneerrors.AgentInstallFailed, "Cannot read the checksum for "+spec, oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+	}
+	if result.ExitCode != 0 {
+		return oneerrors.New(oneerrors.AgentInstallFailed, fmt.Sprintf("%s is not available on %s", spec, registry), oneerrors.WithRetryable(true))
+	}
+	reported := strings.TrimSpace(result.Stdout)
+	if reported != expected {
+		return oneerrors.New(oneerrors.AgentInstallFailed, fmt.Sprintf("Checksum mismatch for %s on %s: manifest expects %s, registry reports %s", spec, registry, expected, valueOrNone(reported)))
+	}
+	return nil
+}
+
+func InstallLockedAgent(ctx context.Context, runtime Runtime, agentID string, agent catalog.Agent, options Options) (Result, error) {
+	if err := checkContext(ctx); err != nil {
+		return Result{}, err
+	}
+	if agent.Package == nil {
+		return Result{}, prerequisiteError(fmt.Sprintf("%s has no package installation contract", agent.Name))
+	}
+	packageInfo := *agent.Package
+	locked := packageInfo.Version
+	result := Result{LockedVersion: locked}
+	var executable string
+	if agent.Command != "" && runtime.Runner != nil {
+		executable, _ = runtime.Runner.LookPath(agent.Command)
+	}
+	current := ""
+	if executable != "" {
+		current = InstalledVersion(ctx, runtime, agent)
+		if !options.EnforceLocked {
+			result.Version = current
+			return result, nil
+		}
+		if current == locked {
+			result.Version = current
+			return result, nil
+		}
+	}
+
+	if err := requirePrerequisites(ctx, runtime, agent); err != nil {
+		return Result{}, err
+	}
+	registry, err := ResolveRegistry(options.Registry)
+	if err != nil {
+		return Result{}, err
+	}
+	manager := packageInfo.Manager
+	packageName := packageInfo.Name
+	var argv []string
+	environment := map[string]string{}
+	switch manager {
+	case "npm":
+		npm, ok := runtime.Runner.LookPath("npm")
+		if !ok || npm == "" {
+			return Result{}, prerequisiteError(fmt.Sprintf("npm is required to install %s", agent.Name))
+		}
+		// A managed Node has no writable system prefix, and a system Node often
+		// needs sudo for -g. Directing global installs at OneAgent's own prefix
+		// makes both cases work without elevation and keeps the Agent CLIs on
+		// the same PATH entry the runtime bootstrap already records.
+		if managedNPM(runtime, npm) {
+			environment["npm_config_prefix"] = GlobalPrefix(runtime.Home)
+		}
+		spec := packageName
+		if !options.Latest {
+			spec += "@" + locked
+			if err := VerifyNPMIntegrity(ctx, runtime, npm, spec, pointerValue(packageInfo.Integrity), registry, options.Timeout); err != nil {
+				return Result{}, err
+			}
+		}
+		if registry != officialRegistry() {
+			environment["npm_config_registry"] = registry
+		}
+		argv = []string{npm, "install", "-g", spec}
+	case "uv":
+		uv, ok := runtime.Runner.LookPath("uv")
+		if !ok || uv == "" {
+			return Result{}, prerequisiteError("uv is required to install Aider")
+		}
+		spec := packageName
+		if !options.Latest {
+			spec += "==" + locked
+		}
+		// uv resolves Python itself. When a matching interpreter is already on
+		// the machine it is reused; otherwise uv downloads a managed CPython
+		// into OneAgent's runtime root, which is why a preinstalled Python 3.12
+		// is no longer a prerequisite for Aider.
+		environment["UV_PYTHON_INSTALL_DIR"] = filepath.Join(RuntimeRoot(runtime.Home), "python")
+		environment["UV_TOOL_BIN_DIR"] = GlobalBinDir(runtime.Home, runtime.Platform.OS)
+		argv = []string{uv, "tool", "install", "--force", "--python", AiderPythonVersion, spec}
+	default:
+		return Result{}, prerequisiteError(fmt.Sprintf("No allowlisted package manager for %s", agent.Name))
+	}
+	commandResult, runErr := runtime.command(ctx, argv, environment, runtime.timeout(options.Timeout))
+	if runErr != nil {
+		if isContextError(runErr) {
+			return Result{}, oneerrors.New(oneerrors.Timeout, fmt.Sprintf("Installing %s timed out", agent.Name), oneerrors.WithRetryable(true), oneerrors.WithCause(runErr))
+		}
+		return Result{}, oneerrors.New(oneerrors.AgentInstallFailed, fmt.Sprintf("Cannot start installer for %s", agent.Name), oneerrors.WithRetryable(true), oneerrors.WithCause(runErr))
+	}
+	if commandResult.ExitCode != 0 {
+		detail := installerFailureDetail(commandResult, runtime.Env)
+		message := fmt.Sprintf("Installing %s failed with exit code %d", agent.Name, commandResult.ExitCode)
+		if detail != "" {
+			message += ": " + detail
+		}
+		return Result{}, oneerrors.New(oneerrors.AgentInstallFailed, message, oneerrors.WithRetryable(true))
+	}
+	result.Installed = true
+	if !options.Latest {
+		result.Version = locked
+	}
+	result.Registry = registry
+	return result, nil
+}
+
+func requirePrerequisites(ctx context.Context, runtime Runtime, agent catalog.Agent) error {
+	if runtime.Runner == nil {
+		return prerequisiteError("A process runner is required for Agent installation")
+	}
+	packageInfo := agent.Package
+	if packageInfo == nil {
+		return prerequisiteError(fmt.Sprintf("%s has no package installation contract", agent.Name))
+	}
+	if packageInfo.Manager == "npm" {
+		if _, ok := runtime.Runner.LookPath("npm"); !ok {
+			return prerequisiteError(fmt.Sprintf("npm is required to install %s. Install the Node.js runtime first.", agent.Name))
+		}
+	}
+	if packageInfo.Manager == "uv" {
+		if _, ok := runtime.Runner.LookPath("uv"); !ok {
+			return prerequisiteError("uv is required to install Aider. Install the uv runtime first.")
+		}
+	}
+	if runtime.Platform.OS == "windows" {
+		missing := make([]string, 0)
+		for _, prerequisite := range agent.WindowsPrerequisites {
+			if _, ok := runtime.Runner.LookPath(prerequisite); !ok {
+				missing = append(missing, prerequisite)
+			}
+		}
+		if len(missing) > 0 {
+			sort.Strings(missing)
+			return prerequisiteError(fmt.Sprintf("%s is required for %s on Windows", missing[0], agent.Name))
+		}
+	}
+	return nil
+}
+
+func installerFailureDetail(result process.Result, environment map[string]string) string {
+	text := redact(result.Stderr+"\n"+result.Stdout, secretValues(environment))
+	text = ansiPattern.ReplaceAllString(text, "")
+	lines := make([]string, 0)
+	for line := range strings.SplitSeq(text, "\n") {
+		line = strings.TrimSpace(line)
+		if line != "" {
+			lines = append(lines, line)
+		}
+	}
+	if len(lines) > 3 {
+		lines = lines[len(lines)-3:]
+	}
+	return trimRunes(strings.Join(lines, " | "), 600)
+}
+
+func Redact(text string, secrets []string) string {
+	return redact(text, secrets)
+}
+
+func redact(text string, secrets []string) string {
+	for _, secret := range secrets {
+		if secret != "" {
+			text = strings.ReplaceAll(text, secret, "[redacted]")
+		}
+	}
+	return text
+}
+
+func secretValues(environment map[string]string) []string {
+	values := make([]string, 0)
+	for key, value := range environment {
+		upper := strings.ToUpper(key)
+		if value != "" && (strings.Contains(upper, "KEY") || strings.Contains(upper, "TOKEN") || strings.Contains(upper, "SECRET") || strings.Contains(upper, "PASSWORD")) {
+			values = append(values, value)
+		}
+	}
+	sort.Strings(values)
+	return values
+}
+
+func isContextError(err error) bool {
+	return errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded)
+}
+
+func checkContext(ctx context.Context) error {
+	if ctx == nil {
+		return nil
+	}
+	if err := ctx.Err(); err != nil {
+		return timeoutError("Agent installation request was cancelled", err)
+	}
+	return nil
+}
+
+func timeoutError(message string, cause error) error {
+	return oneerrors.New(oneerrors.Timeout, message, oneerrors.WithRetryable(true), oneerrors.WithCause(cause))
+}
+
+func prerequisiteError(message string) error {
+	return oneerrors.New(oneerrors.PrerequisiteMissing, message)
+}
+
+func pointerValue(value *string) string {
+	if value == nil {
+		return ""
+	}
+	return *value
+}
+
+func valueOrNone(value string) string {
+	if value == "" {
+		return "(none)"
+	}
+	return value
+}
+
+func officialRegistry() string {
+	for _, mirror := range catalog.Mirrors() {
+		if mirror.ID == "official" {
+			return mirror.Registry
+		}
+	}
+	return "https://registry.npmjs.org/"
+}
+
+func trimRunes(value string, limit int) string {
+	if limit <= 0 {
+		return ""
+	}
+	runes := []rune(value)
+	if len(runes) <= limit {
+		return value
+	}
+	return string(runes[:limit])
+}
+
+var ansiPattern = regexp.MustCompile(`\x1b\[[0-9;]*m`)
diff --git a/internal/install/install_test.go b/internal/install/install_test.go
new file mode 100644
index 00000000..a8d4dc70
--- /dev/null
+++ b/internal/install/install_test.go
@@ -0,0 +1,274 @@
+package install
+
+import (
+	"context"
+	"reflect"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+)
+
+type fakeInstallRunner struct {
+	paths    map[string]string
+	calls    [][]string
+	lastCall []string
+	envs     []map[string]string
+	run      func([]string, map[string]string) (process.Result, error)
+	version  string
+}
+
+func (r *fakeInstallRunner) LookPath(command string) (string, bool) {
+	path, ok := r.paths[command]
+	return path, ok
+}
+
+func (r *fakeInstallRunner) Run(_ context.Context, argv []string, env map[string]string, _ time.Duration) (process.Result, error) {
+	runnerArgs := append([]string(nil), argv...)
+	r.calls = append(r.calls, runnerArgs)
+	r.lastCall = runnerArgs
+	r.envs = append(r.envs, cloneEnv(env))
+	if r.run != nil {
+		return r.run(argv, env)
+	}
+	if strings.Contains(strings.Join(argv, " "), "dist.integrity") {
+		return r.integrityResult(argv), nil
+	}
+	if containsArg(argv, "--version") {
+		version := r.version
+		if version == "" {
+			version = "0.0.1"
+		}
+		return process.Result{Args: runnerArgs, ExitCode: 0, Stdout: "tool " + version}, nil
+	}
+	return r.installResult(argv), nil
+}
+
+func (r *fakeInstallRunner) integrityResult(argv []string) process.Result {
+	name := ""
+	if len(argv) > 2 {
+		spec := argv[2]
+		if index := strings.LastIndex(spec, "@"); index > 0 {
+			spec = spec[:index]
+		}
+		name = spec
+	}
+	for _, id := range catalog.AgentIDs(mustManifest()) {
+		agent := mustManifest().Agents[id]
+		if agent.Package != nil && agent.Package.Name == name && agent.Package.Integrity != nil {
+			return process.Result{Args: append([]string(nil), argv...), ExitCode: 0, Stdout: *agent.Package.Integrity + "\n"}
+		}
+	}
+	return process.Result{Args: append([]string(nil), argv...), ExitCode: 0}
+}
+
+func (r *fakeInstallRunner) installResult(argv []string) process.Result {
+	return process.Result{Args: append([]string(nil), argv...), ExitCode: 0}
+}
+
+func mustManifest() catalog.Manifest {
+	manifest, err := catalog.LoadEmbedded()
+	if err != nil {
+		panic(err)
+	}
+	return manifest
+}
+
+func containsArg(argv []string, wanted string) bool {
+	return slices.Contains(argv, wanted)
+}
+
+func runtimeForInstall(runner process.Runner, osID string, env map[string]string) Runtime {
+	return Runtime{
+		Home:     "/tmp/oneagent-install",
+		Platform: platform.Info{OS: osID, Arch: "x64", Shell: "bash"},
+		Env:      env,
+		Runner:   runner,
+	}
+}
+
+func TestVersionFromOutputAndInstalledVersion(t *testing.T) {
+	for input, want := range map[string]string{
+		"codex-cli 0.145.0":               "0.145.0",
+		"v2.1.217\n":                      "2.1.217",
+		"release 1.2.3-beta.1+build":      "1.2.3-beta.1+build",
+		"version 12.4.0 and 9.0.0":        "12.4.0",
+		"no version":                      "",
+		"embedded 10.20 is not a version": "",
+	} {
+		if got := VersionFromOutput(input); got != want {
+			t.Errorf("VersionFromOutput(%q) = %q, want %q", input, got, want)
+		}
+	}
+	runner := &fakeInstallRunner{paths: map[string]string{"agent": "/bin/agent"}}
+	runtime := runtimeForInstall(runner, "linux", nil)
+	agent := catalog.Agent{Command: "agent", VersionArgs: []string{"--version"}}
+	if got := InstalledVersion(context.Background(), runtime, agent); got != "0.0.1" {
+		t.Fatalf("InstalledVersion() = %q", got)
+	}
+}
+
+func TestResolveRegistryValidatesHTTPSAndMirrors(t *testing.T) {
+	if got, err := ResolveRegistry(""); err != nil || got != "https://registry.npmjs.org/" {
+		t.Fatalf("default registry = %q, %v", got, err)
+	}
+	if got, err := ResolveRegistry("official"); err != nil || got != "https://registry.npmjs.org/" {
+		t.Fatalf("official registry = %q, %v", got, err)
+	}
+	if got, err := ResolveRegistry("https://npm.example.com"); err != nil || got != "https://npm.example.com/" {
+		t.Fatalf("custom registry = %q, %v", got, err)
+	}
+	for _, value := range []string{"http://npm.example.com", "https://user:secret@npm.example.com", "https://npm.example.com/\nheader"} {
+		if _, err := ResolveRegistry(value); err == nil || oneerrors.As(err).Code != oneerrors.InvalidRequest {
+			t.Errorf("invalid registry %q returned %v", value, err)
+		}
+	}
+}
+
+func TestInstallLockedNPMUsesPinnedIntegrityAndMirrorEnvironment(t *testing.T) {
+	manifest := mustManifest()
+	agent := manifest.Agents["codex"]
+	runner := &fakeInstallRunner{paths: map[string]string{"npm": "/fake/npm"}}
+	runtime := runtimeForInstall(runner, "linux", map[string]string{"PATH": "/bin"})
+	result, err := InstallLockedAgent(context.Background(), runtime, "codex", agent, Options{EnforceLocked: true, Registry: "npmmirror"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !result.Installed || result.Version != agent.Package.Version || result.Registry != "https://registry.npmmirror.com/" {
+		t.Fatalf("install result = %#v", result)
+	}
+	if len(runner.envs) != 2 || runner.envs[0]["npm_config_registry"] != "" || runner.envs[1]["npm_config_registry"] != "https://registry.npmmirror.com/" {
+		t.Fatalf("runner environments = %#v", runner.envs)
+	}
+	if !reflect.DeepEqual(runner.lastCall, []string{"/fake/npm", "install", "-g", "@openai/codex@0.145.0"}) {
+		t.Fatalf("last command = %#v", runner.lastCall)
+	}
+}
+
+func TestInstallLockedAgentShortCircuitsAndSupportsLatest(t *testing.T) {
+	manifest := mustManifest()
+	agent := manifest.Agents["codex"]
+	runner := &fakeInstallRunner{paths: map[string]string{"npm": "/fake/npm", "codex": "/fake/codex"}, version: agent.Package.Version}
+	runtime := runtimeForInstall(runner, "linux", nil)
+	result, err := InstallLockedAgent(context.Background(), runtime, "codex", agent, Options{EnforceLocked: true})
+	if err != nil || result.Installed || result.Version != agent.Package.Version || len(runner.calls) != 1 {
+		t.Fatalf("unlocked version result = %#v, err=%v, calls=%#v", result, err, runner.calls)
+	}
+	runner = &fakeInstallRunner{paths: map[string]string{"npm": "/fake/npm", "codex": "/fake/codex"}}
+	runtime.Runner = runner
+	result, err = InstallLockedAgent(context.Background(), runtime, "codex", agent, Options{EnforceLocked: false})
+	if err != nil || result.Installed || result.Version != "0.0.1" {
+		t.Fatalf("non-enforced result = %#v, err=%v", result, err)
+	}
+	runner = &fakeInstallRunner{paths: map[string]string{"npm": "/fake/npm"}}
+	runtime.Runner = runner
+	result, err = InstallLockedAgent(context.Background(), runtime, "codex", agent, Options{EnforceLocked: true, Latest: true})
+	if err != nil || !result.Installed || result.Version != "" {
+		t.Fatalf("latest result = %#v, err=%v", result, err)
+	}
+	if !reflect.DeepEqual(runner.lastCall, []string{"/fake/npm", "install", "-g", "@openai/codex"}) {
+		t.Fatalf("latest command = %#v", runner.lastCall)
+	}
+}
+
+func TestInstallLockedAgentSupportsAiderRuntimeBoundary(t *testing.T) {
+	manifest := mustManifest()
+	agent := manifest.Agents["aider"]
+	runner := &fakeInstallRunner{paths: map[string]string{"uv": "/fake/uv", "python3.12": "/fake/python"}}
+	runtime := runtimeForInstall(runner, "linux", nil)
+	result, err := InstallLockedAgent(context.Background(), runtime, "aider", agent, Options{EnforceLocked: true})
+	if err != nil || !result.Installed {
+		t.Fatalf("uv result = %#v, err=%v", result, err)
+	}
+	// uv resolves the interpreter itself: OneAgent requests 3.12 and lets uv
+	// reuse a system Python or download a managed one into its own root.
+	if !reflect.DeepEqual(runner.lastCall, []string{"/fake/uv", "tool", "install", "--force", "--python", "3.12", "aider-chat==0.86.2"}) {
+		t.Fatalf("uv command = %#v", runner.lastCall)
+	}
+	installEnv := runner.envs[len(runner.envs)-1]
+	if !strings.HasSuffix(installEnv["UV_PYTHON_INSTALL_DIR"], "/.oneagent/runtimes/python") {
+		t.Fatalf("uv python install dir = %q", installEnv["UV_PYTHON_INSTALL_DIR"])
+	}
+	if !strings.HasSuffix(installEnv["UV_TOOL_BIN_DIR"], "/.oneagent/runtimes/global/bin") {
+		t.Fatalf("uv tool bin dir = %q", installEnv["UV_TOOL_BIN_DIR"])
+	}
+
+	pythonRunner := &fakeInstallRunner{paths: map[string]string{"python3": "/fake/python3"}}
+	pythonRunner.run = func(argv []string, _ map[string]string) (process.Result, error) {
+		return process.Result{Args: argv, ExitCode: 0, Stdout: "Python 3.12.9"}, nil
+	}
+	pythonRuntime := runtimeForInstall(pythonRunner, "linux", nil)
+	if got, err := ResolveAiderPython312(context.Background(), pythonRuntime); err != nil || got != "/fake/python3" {
+		t.Fatalf("python3 resolution = %q, %v", got, err)
+	}
+
+	windowsRunner := &fakeInstallRunner{paths: map[string]string{"py": "py.exe"}}
+	windowsRunner.run = func(argv []string, _ map[string]string) (process.Result, error) {
+		return process.Result{Args: argv, ExitCode: 0, Stdout: "Python 3.12.7"}, nil
+	}
+	windowsRuntime := runtimeForInstall(windowsRunner, "windows", nil)
+	if got, err := ResolveAiderPython312(context.Background(), windowsRuntime); err != nil || got != "3.12" {
+		t.Fatalf("py launcher resolution = %q, %v", got, err)
+	}
+}
+
+func TestInstallPrerequisitesAndFailuresAreStableAndRedacted(t *testing.T) {
+	manifest := mustManifest()
+	agent := manifest.Agents["codex"]
+	missing := &fakeInstallRunner{paths: map[string]string{}}
+	_, err := InstallLockedAgent(context.Background(), runtimeForInstall(missing, "linux", nil), "codex", agent, Options{EnforceLocked: true})
+	if err == nil || oneerrors.As(err).Code != oneerrors.PrerequisiteMissing || !strings.Contains(err.Error(), "npm") {
+		t.Fatalf("missing npm error = %v", err)
+	}
+
+	secret := "install-secret"
+	failing := &fakeInstallRunner{paths: map[string]string{"npm": "/fake/npm"}}
+	failing.run = func(argv []string, _ map[string]string) (process.Result, error) {
+		if strings.Contains(strings.Join(argv, " "), "dist.integrity") {
+			return failing.integrityResult(argv), nil
+		}
+		return process.Result{Args: argv, ExitCode: 9, Stderr: "failed with " + secret}, nil
+	}
+	runtime := runtimeForInstall(failing, "linux", map[string]string{"API_KEY": secret})
+	_, err = InstallLockedAgent(context.Background(), runtime, "codex", agent, Options{EnforceLocked: true})
+	if err == nil || oneerrors.As(err).Code != oneerrors.AgentInstallFailed || strings.Contains(err.Error(), secret) || !strings.Contains(err.Error(), "[redacted]") {
+		t.Fatalf("redacted install failure = %v", err)
+	}
+
+	timed := &fakeInstallRunner{paths: map[string]string{"npm": "/fake/npm"}}
+	timed.run = func(argv []string, _ map[string]string) (process.Result, error) {
+		if strings.Contains(strings.Join(argv, " "), "dist.integrity") {
+			return timed.integrityResult(argv), nil
+		}
+		return process.Result{Args: argv, ExitCode: -1}, context.DeadlineExceeded
+	}
+	_, err = InstallLockedAgent(context.Background(), runtimeForInstall(timed, "linux", nil), "codex", agent, Options{EnforceLocked: true})
+	if err == nil || oneerrors.As(err).Code != oneerrors.Timeout {
+		t.Fatalf("timeout install error = %v", err)
+	}
+
+	if err := VerifyNPMIntegrity(context.Background(), runtime, "/fake/npm", "pkg@1", "sha512-expected", "https://registry.example/", time.Second); err == nil {
+		t.Fatal("mismatched integrity unexpectedly succeeded")
+	}
+}
+
+func TestResolveAiderRuntimeMissingIsPrerequisiteError(t *testing.T) {
+	runner := &fakeInstallRunner{paths: map[string]string{}}
+	_, err := ResolveAiderPython312(context.Background(), runtimeForInstall(runner, "linux", nil))
+	if err == nil || oneerrors.As(err).Code != oneerrors.PrerequisiteMissing {
+		t.Fatalf("missing Python error = %v", err)
+	}
+}
+
+func TestInstallerFailureDetailLimitsLinesAndLength(t *testing.T) {
+	result := process.Result{Stderr: "one\ntwo\nthree\nfour\n" + strings.Repeat("x", 700)}
+	detail := installerFailureDetail(result, nil)
+	if strings.Contains(detail, "one") || !strings.Contains(detail, "four") || len([]rune(detail)) > 600 {
+		t.Fatalf("failure detail = %q", detail)
+	}
+}
diff --git a/internal/install/path.go b/internal/install/path.go
new file mode 100644
index 00000000..f51e737b
--- /dev/null
+++ b/internal/install/path.go
@@ -0,0 +1,205 @@
+package install
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+// pathMarker delimits the block OneAgent owns in a shell profile. Every write
+// rewrites the whole block, so a version bump cannot leave a stale directory
+// behind and repeated runs cannot append duplicates.
+const (
+	pathMarkerBegin = "# >>> OneAgent managed runtimes >>>"
+	pathMarkerEnd   = "# <<< OneAgent managed runtimes <<<"
+	envScriptName   = "runtime-path.sh"
+)
+
+// GlobalPrefix is the npm global prefix for managed installs. It is deliberately
+// outside the versioned runtime directory so an Agent CLI installed today keeps
+// working after the locked Node version changes.
+func GlobalPrefix(home string) string {
+	return filepath.Join(RuntimeRoot(home), "global")
+}
+
+// GlobalBinDir is where the global prefix puts executables. npm follows the
+// platform convention: a bin subdirectory on POSIX, the prefix root on Windows.
+func GlobalBinDir(home, osID string) string {
+	if osID == "windows" {
+		return GlobalPrefix(home)
+	}
+	return filepath.Join(GlobalPrefix(home), "bin")
+}
+
+// ManagedPathDirs lists the directories that must be on PATH for managed
+// runtimes and the Agent CLIs they install. Only installed runtimes contribute,
+// so PATH never names a directory that does not exist.
+func ManagedPathDirs(home, osID, arch string, manifest catalog.RuntimeManifest) []string {
+	key := catalog.RuntimeArtifactKey(osID, arch)
+	dirs := make([]string, 0, len(manifest.Runtimes)+1)
+	for _, id := range manifest.RuntimeOrder {
+		entry := manifest.Runtimes[id]
+		artifact, ok := entry.Artifacts[key]
+		if !ok {
+			continue
+		}
+		if binDir := ManagedBinDir(home, id, entry, artifact); binDir != "" {
+			dirs = append(dirs, binDir)
+		}
+	}
+	if len(dirs) > 0 {
+		if _, err := os.Stat(GlobalBinDir(home, osID)); err == nil {
+			dirs = append(dirs, GlobalBinDir(home, osID))
+		}
+	}
+	return dirs
+}
+
+// PersistRuntimePath records the managed directories in the user's login
+// environment so an Agent CLI installed through OneAgent also resolves in the
+// user's own terminal, and so a later run detects the runtime instead of
+// downloading it again.
+//
+// It is idempotent: the POSIX path is one sourced script referenced from a
+// marked block, and the Windows path rewrites only the user PATH entries that
+// live under OneAgent's runtime root.
+func PersistRuntimePath(ctx context.Context, runtime Runtime, filesystem securefs.Store, dirs []string) (bool, error) {
+	if len(dirs) == 0 {
+		return false, nil
+	}
+	if runtime.Platform.OS == "windows" {
+		return persistWindowsPath(ctx, runtime, dirs)
+	}
+	return persistPosixPath(ctx, runtime, filesystem, dirs)
+}
+
+func persistPosixPath(ctx context.Context, runtime Runtime, filesystem securefs.Store, dirs []string) (bool, error) {
+	script := filepath.Join(RuntimeRoot(runtime.Home), envScriptName)
+	if err := filesystem.EnsurePrivateDir(ctx, RuntimeRoot(runtime.Home)); err != nil {
+		return false, err
+	}
+	builder := &strings.Builder{}
+	builder.WriteString("# Generated by OneAgent. Edits are overwritten.\n")
+	for _, directory := range dirs {
+		// The guard keeps a re-sourced profile from growing PATH without bound.
+		fmt.Fprintf(builder, "case \":$PATH:\" in\n  *\":%s:\"*) ;;\n  *) PATH=\"%s:$PATH\" ;;\nesac\n", directory, directory)
+	}
+	builder.WriteString("export PATH\n")
+	if _, err := filesystem.AtomicWrite(ctx, script, []byte(builder.String()), false); err != nil {
+		return false, err
+	}
+	changed := false
+	for _, profile := range shellProfiles(runtime.Home) {
+		updated, err := ensureProfileBlock(ctx, filesystem, profile, script)
+		if err != nil {
+			return changed, err
+		}
+		changed = changed || updated
+	}
+	return changed, nil
+}
+
+// shellProfiles returns the login files to reference the script from. An
+// existing file is updated; when none exists, ~/.profile is created so the
+// entry is not silently dropped.
+func shellProfiles(home string) []string {
+	candidates := []string{".zshrc", ".bashrc", ".bash_profile", ".profile"}
+	existing := make([]string, 0, len(candidates))
+	for _, name := range candidates {
+		path := filepath.Join(home, name)
+		if _, err := os.Stat(path); err == nil {
+			existing = append(existing, path)
+		}
+	}
+	if len(existing) == 0 {
+		return []string{filepath.Join(home, ".profile")}
+	}
+	return existing
+}
+
+func ensureProfileBlock(ctx context.Context, filesystem securefs.Store, profile, script string) (bool, error) {
+	current, err := os.ReadFile(profile)
+	if err != nil && !os.IsNotExist(err) {
+		return false, runtimeError("Cannot read "+filepath.Base(profile), err)
+	}
+	block := fmt.Sprintf("%s\n[ -f \"%s\" ] && . \"%s\"\n%s\n", pathMarkerBegin, script, script, pathMarkerEnd)
+	existing := string(current)
+	if strings.Contains(existing, block) {
+		return false, nil
+	}
+	updated := replaceBlock(existing, block)
+	if _, err := filesystem.AtomicWrite(ctx, profile, []byte(updated), false); err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
+// replaceBlock swaps an existing OneAgent block for the new one, or appends it
+// when the file has none.
+func replaceBlock(content, block string) string {
+	begin := strings.Index(content, pathMarkerBegin)
+	end := strings.Index(content, pathMarkerEnd)
+	if begin >= 0 && end > begin {
+		tail := content[end+len(pathMarkerEnd):]
+		return content[:begin] + block + strings.TrimPrefix(tail, "\n")
+	}
+	if content != "" && !strings.HasSuffix(content, "\n") {
+		content += "\n"
+	}
+	return content + block
+}
+
+// persistWindowsPath rewrites the user PATH through PowerShell. It replaces
+// every entry under OneAgent's runtime root rather than appending, so upgrading
+// the locked version cannot accumulate dead directories. The machine-wide PATH
+// is never touched: that would need elevation and affect other users.
+func persistWindowsPath(ctx context.Context, runtime Runtime, dirs []string) (bool, error) {
+	powershell, ok := runtime.Runner.LookPath("powershell")
+	if !ok || powershell == "" {
+		powershell, ok = runtime.Runner.LookPath("pwsh")
+	}
+	if !ok || powershell == "" {
+		return false, prerequisiteError("PowerShell is required to record the runtime directories on PATH")
+	}
+	root := RuntimeRoot(runtime.Home)
+	// The script is passed as one argument with no interpolated user input
+	// beyond the runtime root and the managed directories, all of which are
+	// derived from HOME and the lock file rather than from a request.
+	script := fmt.Sprintf(`$root = %s
+$managed = @(%s)
+$current = [Environment]::GetEnvironmentVariable('Path','User')
+$entries = @()
+if ($current) { $entries = $current -split ';' | Where-Object { $_ -ne '' } }
+$kept = $entries | Where-Object { -not $_.StartsWith($root, [StringComparison]::OrdinalIgnoreCase) }
+$next = @($managed + $kept) -join ';'
+if ($next -ne $current) {
+  [Environment]::SetEnvironmentVariable('Path', $next, 'User')
+  Write-Output 'updated'
+}`, powershellQuote(root), powershellList(dirs))
+
+	result, err := runtime.command(ctx, []string{powershell, "-NoProfile", "-NonInteractive", "-Command", script}, nil, VersionCommandTimeout)
+	if err != nil {
+		return false, runtimeError("Cannot record the runtime directories on PATH", err)
+	}
+	if result.ExitCode != 0 {
+		return false, runtimeError("Cannot record the runtime directories on PATH", fmt.Errorf("powershell exited with %d", result.ExitCode))
+	}
+	return strings.Contains(result.Stdout, "updated"), nil
+}
+
+func powershellQuote(value string) string {
+	return "'" + strings.ReplaceAll(value, "'", "''") + "'"
+}
+
+func powershellList(values []string) string {
+	quoted := make([]string, 0, len(values))
+	for _, value := range values {
+		quoted = append(quoted, powershellQuote(value))
+	}
+	return strings.Join(quoted, ",")
+}
diff --git a/internal/install/runtime.go b/internal/install/runtime.go
new file mode 100644
index 00000000..d4281927
--- /dev/null
+++ b/internal/install/runtime.go
@@ -0,0 +1,92 @@
+// Package install contains the transport-independent Agent installation
+// workflow. It is intentionally separate from Wails bindings so the CLI can
+// use the same checks and command construction.
+package install
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"maps"
+	"time"
+
+	"github.com/MaimoryLab/OneAgent/internal/platform"
+	"github.com/MaimoryLab/OneAgent/internal/process"
+)
+
+const (
+	DefaultCommandTimeout = 180 * time.Second
+	VersionCommandTimeout = 30 * time.Second
+)
+
+type Runtime struct {
+	Home     string
+	Platform platform.Info
+	Env      map[string]string
+	Runner   process.Runner
+	OnOutput process.OutputListener
+}
+
+func NewRuntime(home string, info platform.Info, runner process.Runner, env map[string]string) Runtime {
+	if info.OS == "" {
+		info = platform.Current()
+	}
+	if home == "" {
+		home = platform.ResolveHome(env, info.OS)
+	}
+	if runner == nil {
+		current := process.Current()
+		runner = current
+		if env == nil {
+			env = current.Env
+		}
+	}
+	return Runtime{Home: home, Platform: info, Env: cloneEnv(env), Runner: runner}
+}
+
+func CurrentRuntime() Runtime {
+	info := platform.Current()
+	current := process.Current()
+	return NewRuntime(platform.ResolveHome(current.Env, info.OS), info, current, current.Env)
+}
+
+func (r Runtime) command(ctx context.Context, argv []string, env map[string]string, timeout time.Duration) (process.Result, error) {
+	if r.Runner == nil {
+		return process.Result{Args: append([]string(nil), argv...), ExitCode: -1}, fmt.Errorf("process runner is not configured")
+	}
+	overrides := cloneEnv(r.Env)
+	maps.Copy(overrides, env)
+	if r.OnOutput != nil {
+		r.OnOutput(process.Output{Kind: "command", Args: append([]string(nil), argv...)})
+	}
+	var result process.Result
+	var err error
+	if runner, ok := r.Runner.(process.StreamingRunner); ok {
+		result, err = runner.RunWithOutput(ctx, argv, overrides, timeout, r.OnOutput)
+	} else {
+		result, err = r.Runner.Run(ctx, argv, overrides, timeout)
+	}
+	if err == nil {
+		return result, nil
+	}
+	if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+		return result, err
+	}
+	return result, err
+}
+
+func (r Runtime) timeout(value time.Duration) time.Duration {
+	if value > 0 {
+		return value
+	}
+	return DefaultCommandTimeout
+}
+
+func cloneEnv(source map[string]string) map[string]string {
+	if source == nil {
+		return map[string]string{}
+	}
+	result := make(map[string]string, len(source))
+	maps.Copy(result, source)
+	return result
+}
diff --git a/internal/jsonorder/document.go b/internal/jsonorder/document.go
new file mode 100644
index 00000000..d716137f
--- /dev/null
+++ b/internal/jsonorder/document.go
@@ -0,0 +1,375 @@
+// Package jsonorder edits JSON objects without reordering them.
+//
+// encoding/json sorts map keys when it writes them. Config adapters use this
+// package so rewriting a user's file changes only the fields OneAgent manages.
+package jsonorder
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+)
+
+// Object is a JSON object that remembers the order its keys arrived in.
+// Existing keys are updated in place; new keys are appended.
+type Object struct {
+	keys   []string
+	values map[string]any
+}
+
+// NewObject builds an empty object.
+func NewObject() *Object {
+	return &Object{values: map[string]any{}}
+}
+
+// Len reports the number of keys in the object.
+func (o *Object) Len() int {
+	if o == nil {
+		return 0
+	}
+	return len(o.keys)
+}
+
+// Keys returns keys in their current order.
+func (o *Object) Keys() []string {
+	if o == nil {
+		return nil
+	}
+	return append([]string(nil), o.keys...)
+}
+
+// Get returns a value and whether the key is present.
+func (o *Object) Get(key string) (any, bool) {
+	if o == nil {
+		return nil, false
+	}
+	value, present := o.values[key]
+	return value, present
+}
+
+// Set updates an existing key in place, or appends a new key.
+func (o *Object) Set(key string, value any) {
+	if o.values == nil {
+		o.values = map[string]any{}
+	}
+	if _, present := o.values[key]; !present {
+		o.keys = append(o.keys, key)
+	}
+	o.values[key] = value
+}
+
+// Delete removes a key and preserves the order of the remaining keys.
+func (o *Object) Delete(key string) {
+	if o == nil {
+		return
+	}
+	if _, present := o.values[key]; !present {
+		return
+	}
+	delete(o.values, key)
+	for index, existing := range o.keys {
+		if existing == key {
+			o.keys = append(o.keys[:index], o.keys[index+1:]...)
+			return
+		}
+	}
+}
+
+// Child returns the nested object at key, creating it when absent. It refuses
+// to replace a non-object value because doing so would discard user data.
+func (o *Object) Child(key string) (*Object, error) {
+	existing, present := o.Get(key)
+	if !present || existing == nil {
+		child := NewObject()
+		o.Set(key, child)
+		return child, nil
+	}
+	child, ok := existing.(*Object)
+	if !ok {
+		return nil, fmt.Errorf("%q is %s, not an object", key, describe(existing))
+	}
+	return child, nil
+}
+
+// GetString returns a string value, or an empty string for another type.
+func (o *Object) GetString(key string) string {
+	value, present := o.Get(key)
+	if !present {
+		return ""
+	}
+	text, ok := value.(string)
+	if !ok {
+		return ""
+	}
+	return text
+}
+
+// GetObject returns a nested object without creating one.
+func (o *Object) GetObject(key string) (*Object, bool) {
+	value, present := o.Get(key)
+	if !present {
+		return nil, false
+	}
+	child, ok := value.(*Object)
+	return child, ok
+}
+
+// MarshalJSON lets an Object nested in an ordinary struct retain its contents.
+func (o *Object) MarshalJSON() ([]byte, error) {
+	if o == nil {
+		return []byte("null"), nil
+	}
+	var buffer bytes.Buffer
+	if err := writeValue(&buffer, o, 0); err != nil {
+		return nil, err
+	}
+	return buffer.Bytes(), nil
+}
+
+// UnmarshalJSON reads an object and records key order.
+func (o *Object) UnmarshalJSON(raw []byte) error {
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.UseNumber()
+	token, err := decoder.Token()
+	if err != nil {
+		return err
+	}
+	delimiter, ok := token.(json.Delim)
+	if !ok || delimiter != '{' {
+		return fmt.Errorf("expected a JSON object")
+	}
+	o.keys = nil
+	o.values = map[string]any{}
+	return o.decodeInto(decoder)
+}
+
+func (o *Object) decodeInto(decoder *json.Decoder) error {
+	for decoder.More() {
+		token, err := decoder.Token()
+		if err != nil {
+			return err
+		}
+		key, ok := token.(string)
+		if !ok {
+			return fmt.Errorf("expected an object key")
+		}
+		value, err := decodeValue(decoder)
+		if err != nil {
+			return err
+		}
+		o.Set(key, value)
+	}
+	_, err := decoder.Token()
+	return err
+}
+
+func decodeValue(decoder *json.Decoder) (any, error) {
+	token, err := decoder.Token()
+	if err != nil {
+		return nil, err
+	}
+	if delimiter, ok := token.(json.Delim); ok {
+		switch delimiter {
+		case '{':
+			child := NewObject()
+			if err := child.decodeInto(decoder); err != nil {
+				return nil, err
+			}
+			return child, nil
+		case '[':
+			items := []any{}
+			for decoder.More() {
+				item, err := decodeValue(decoder)
+				if err != nil {
+					return nil, err
+				}
+				items = append(items, item)
+			}
+			if _, err := decoder.Token(); err != nil {
+				return nil, err
+			}
+			return items, nil
+		default:
+			return nil, fmt.Errorf("unexpected %v", delimiter)
+		}
+	}
+	return token, nil
+}
+
+// Parse reads a JSON object, preserving key order.
+func Parse(raw []byte) (*Object, error) {
+	object := NewObject()
+	if err := json.Unmarshal(raw, object); err != nil {
+		return nil, err
+	}
+	return object, nil
+}
+
+// Marshal renders an object with two-space indentation and one trailing
+// newline, matching json.dumps(..., ensure_ascii=False, indent=2) plus the
+// newline used by OneAgent's config files.
+func Marshal(object *Object) ([]byte, error) {
+	var buffer bytes.Buffer
+	if err := writeValue(&buffer, object, 0); err != nil {
+		return nil, err
+	}
+	buffer.WriteByte('\n')
+	return buffer.Bytes(), nil
+}
+
+const indentStep = "  "
+
+func writeValue(out io.Writer, value any, depth int) error {
+	switch typed := value.(type) {
+	case *Object:
+		return writeObject(out, typed, depth)
+	case []any:
+		return writeArray(out, typed, depth)
+	case nil:
+		_, err := io.WriteString(out, "null")
+		return err
+	case string:
+		return writeString(out, typed)
+	case bool:
+		if typed {
+			_, err := io.WriteString(out, "true")
+			return err
+		}
+		_, err := io.WriteString(out, "false")
+		return err
+	case json.Number:
+		_, err := io.WriteString(out, renderNumber(typed))
+		return err
+	default:
+		encoded, err := json.Marshal(typed)
+		if err != nil {
+			return err
+		}
+		_, err = out.Write(encoded)
+		return err
+	}
+}
+
+func writeObject(out io.Writer, object *Object, depth int) error {
+	if object == nil || len(object.keys) == 0 {
+		_, err := io.WriteString(out, "{}")
+		return err
+	}
+	if _, err := io.WriteString(out, "{\n"); err != nil {
+		return err
+	}
+	inner := strings.Repeat(indentStep, depth+1)
+	for index, key := range object.keys {
+		if _, err := io.WriteString(out, inner); err != nil {
+			return err
+		}
+		if err := writeString(out, key); err != nil {
+			return err
+		}
+		if _, err := io.WriteString(out, ": "); err != nil {
+			return err
+		}
+		if err := writeValue(out, object.values[key], depth+1); err != nil {
+			return err
+		}
+		if index < len(object.keys)-1 {
+			if _, err := io.WriteString(out, ","); err != nil {
+				return err
+			}
+		}
+		if _, err := io.WriteString(out, "\n"); err != nil {
+			return err
+		}
+	}
+	_, err := io.WriteString(out, strings.Repeat(indentStep, depth)+"}")
+	return err
+}
+
+func writeArray(out io.Writer, items []any, depth int) error {
+	if len(items) == 0 {
+		_, err := io.WriteString(out, "[]")
+		return err
+	}
+	if _, err := io.WriteString(out, "[\n"); err != nil {
+		return err
+	}
+	inner := strings.Repeat(indentStep, depth+1)
+	for index, item := range items {
+		if _, err := io.WriteString(out, inner); err != nil {
+			return err
+		}
+		if err := writeValue(out, item, depth+1); err != nil {
+			return err
+		}
+		if index < len(items)-1 {
+			if _, err := io.WriteString(out, ","); err != nil {
+				return err
+			}
+		}
+		if _, err := io.WriteString(out, "\n"); err != nil {
+			return err
+		}
+	}
+	_, err := io.WriteString(out, strings.Repeat(indentStep, depth)+"]")
+	return err
+}
+
+func writeString(out io.Writer, value string) error {
+	var builder strings.Builder
+	builder.WriteByte('"')
+	for _, character := range value {
+		switch character {
+		case '"':
+			builder.WriteString(`\"`)
+		case '\\':
+			builder.WriteString(`\\`)
+		case '\n':
+			builder.WriteString(`\n`)
+		case '\r':
+			builder.WriteString(`\r`)
+		case '\t':
+			builder.WriteString(`\t`)
+		case '\b':
+			builder.WriteString(`\b`)
+		case '\f':
+			builder.WriteString(`\f`)
+		default:
+			if character < 0x20 {
+				builder.WriteString(fmt.Sprintf(`\u%04x`, character))
+				continue
+			}
+			builder.WriteRune(character)
+		}
+	}
+	builder.WriteByte('"')
+	_, err := io.WriteString(out, builder.String())
+	return err
+}
+
+// SortedKeys returns a sorted copy for diagnostics without changing output
+// order.
+func SortedKeys(object *Object) []string {
+	keys := object.Keys()
+	sort.Strings(keys)
+	return keys
+}
+
+func describe(value any) string {
+	switch value.(type) {
+	case string:
+		return "a string"
+	case bool:
+		return "a boolean"
+	case json.Number:
+		return "a number"
+	case []any:
+		return "an array"
+	case nil:
+		return "null"
+	default:
+		return fmt.Sprintf("%T", value)
+	}
+}
diff --git a/internal/jsonorder/document_test.go b/internal/jsonorder/document_test.go
new file mode 100644
index 00000000..6afea5a4
--- /dev/null
+++ b/internal/jsonorder/document_test.go
@@ -0,0 +1,84 @@
+package jsonorder
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestRoundTripPreservesOrderAndUnicodeEncoding(t *testing.T) {
+	input := `{"zeta":1,"alpha":"通义-max","nested":{"b":true,"a":null},"items":[{"x":1},2]}`
+	object, err := Parse([]byte(input))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, err := Marshal(object)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "{\n  \"zeta\": 1,\n  \"alpha\": \"通义-max\",\n  \"nested\": {\n    \"b\": true,\n    \"a\": null\n  },\n  \"items\": [\n    {\n      \"x\": 1\n    },\n    2\n  ]\n}\n"
+	if string(got) != want {
+		t.Fatalf("got:\n%s\nwant:\n%s", got, want)
+	}
+}
+
+func TestExistingKeysUpdateInPlaceAndNewKeysAppend(t *testing.T) {
+	object, err := Parse([]byte(`{"first":1,"target":"old","last":3}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	object.Set("target", "new")
+	object.Set("added", 4)
+	if got := strings.Join(object.Keys(), ","); got != "first,target,last,added" {
+		t.Fatalf("keys = %s", got)
+	}
+}
+
+func TestChildRejectsWrongTypeAndCreatesMissingObject(t *testing.T) {
+	object, err := Parse([]byte(`{"env":"wrong"}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := object.Child("env"); err == nil {
+		t.Fatal("expected wrong-type error")
+	}
+	fresh := NewObject()
+	child, err := fresh.Child("env")
+	if err != nil {
+		t.Fatal(err)
+	}
+	child.Set("KEY", "value")
+	if got, ok := fresh.GetObject("env"); !ok || got.GetString("KEY") != "value" {
+		t.Fatalf("child was not attached: %#v", fresh)
+	}
+}
+
+func TestMarshalJSONWorksWhenNestedInStruct(t *testing.T) {
+	object := NewObject()
+	object.Set("second", "b")
+	object.Set("first", "a")
+	value, err := json.Marshal(struct {
+		Profile *Object `json:"profile"`
+	}{Profile: object})
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(value)
+	if strings.Index(text, "second") > strings.Index(text, "first") {
+		t.Fatalf("nested object was reordered: %s", text)
+	}
+}
+
+func TestExponentNumbersUseStableRendering(t *testing.T) {
+	object, err := Parse([]byte(`{"large":1e10,"small":1e-5,"plain":1.5}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, err := Marshal(object)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(got), `"large": 10000000000.0`) || !strings.Contains(string(got), `"small": 1e-05`) {
+		t.Fatalf("numbers were not rendered in the stable form: %s", got)
+	}
+}
diff --git a/internal/jsonorder/number.go b/internal/jsonorder/number.go
new file mode 100644
index 00000000..8cfc64b6
--- /dev/null
+++ b/internal/jsonorder/number.go
@@ -0,0 +1,60 @@
+package jsonorder
+
+import (
+	"encoding/json"
+	"strconv"
+	"strings"
+)
+
+// renderNumber preserves the legacy configuration number representation. Plain
+// integers and decimals retain their text; exponent forms use the established
+// fixed/scientific notation rules.
+func renderNumber(number json.Number) string {
+	text := number.String()
+	if !strings.ContainsAny(text, "eE") {
+		return text
+	}
+	value, err := strconv.ParseFloat(text, 64)
+	if err != nil {
+		return text
+	}
+	return renderFloat(value)
+}
+
+func renderFloat(value float64) string {
+	if value != value {
+		return "NaN"
+	}
+	if value > maxFloat {
+		return "Infinity"
+	}
+	if value < -maxFloat {
+		return "-Infinity"
+	}
+	if exponent := decimalExponent(value); exponent < -4 || exponent >= 16 {
+		return strconv.FormatFloat(value, 'e', -1, 64)
+	}
+	text := strconv.FormatFloat(value, 'f', -1, 64)
+	if !strings.Contains(text, ".") {
+		text += ".0"
+	}
+	return text
+}
+
+const maxFloat = 1.7976931348623157e308
+
+func decimalExponent(value float64) int {
+	if value == 0 {
+		return 0
+	}
+	text := strconv.FormatFloat(value, 'e', -1, 64)
+	_, after, ok := strings.Cut(text, "e")
+	if !ok {
+		return 0
+	}
+	exponent, err := strconv.Atoi(after)
+	if err != nil {
+		return 0
+	}
+	return exponent
+}
diff --git a/internal/platform/platform.go b/internal/platform/platform.go
new file mode 100644
index 00000000..816c27d9
--- /dev/null
+++ b/internal/platform/platform.go
@@ -0,0 +1,103 @@
+// Package platform centralizes operating-system and home-directory decisions.
+// It is deliberately injectable so catalog and status tests never touch the
+// developer's real HOME.
+package platform
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+)
+
+type Info struct {
+	OS    string `json:"os"`
+	Arch  string `json:"arch"`
+	Shell string `json:"shell"`
+}
+
+func Current() Info {
+	return For(runtime.GOOS, runtime.GOARCH)
+}
+
+func For(goos, goarch string) Info {
+	osID := normalizeOS(goos)
+	arch := "x64"
+	if goarch == "arm64" || goarch == "aarch64" {
+		arch = "arm64"
+	}
+	shell := "bash"
+	if osID == "windows" {
+		shell = "powershell"
+	}
+	return Info{OS: osID, Arch: arch, Shell: shell}
+}
+
+func normalizeOS(goos string) string {
+	switch strings.ToLower(goos) {
+	case "darwin", "macos":
+		return "macos"
+	case "windows", "win32":
+		return "windows"
+	default:
+		// The product currently has a Linux target for every non-Darwin,
+		// non-Windows Unix platform. This keeps the product's Linux fallback.
+		return "linux"
+	}
+}
+
+// ResolveHome follows the existing precedence exactly: an explicit
+// ONEAGENT_HOME override, then the native Windows variables, then HOME, then
+// the process home fallback.
+func ResolveHome(env map[string]string, osID string) string {
+	values := env
+	if values == nil {
+		values = environ()
+	}
+	if value := strings.TrimSpace(values["ONEAGENT_HOME"]); value != "" {
+		return expandUser(value, values, osID)
+	}
+	if osID == "windows" {
+		if value := values["USERPROFILE"]; value != "" {
+			return value
+		}
+		if drive, path := values["HOMEDRIVE"], values["HOMEPATH"]; drive != "" && path != "" {
+			return drive + path
+		}
+	}
+	if value := values["HOME"]; value != "" {
+		return value
+	}
+	if home, err := os.UserHomeDir(); err == nil {
+		return home
+	}
+	return "."
+}
+
+func environ() map[string]string {
+	values := make(map[string]string)
+	for _, item := range os.Environ() {
+		key, value, ok := strings.Cut(item, "=")
+		if ok {
+			values[key] = value
+		}
+	}
+	return values
+}
+
+func expandUser(value string, env map[string]string, osID string) string {
+	if value != "~" && !strings.HasPrefix(value, "~/") && !strings.HasPrefix(value, `~\`) {
+		return filepath.Clean(value)
+	}
+	home := env["HOME"]
+	if osID == "windows" && env["USERPROFILE"] != "" {
+		home = env["USERPROFILE"]
+	}
+	if home == "" {
+		home, _ = os.UserHomeDir()
+	}
+	if value == "~" {
+		return home
+	}
+	return filepath.Join(home, strings.TrimLeft(value[2:], `/\`))
+}
diff --git a/internal/platform/platform_test.go b/internal/platform/platform_test.go
new file mode 100644
index 00000000..c7268998
--- /dev/null
+++ b/internal/platform/platform_test.go
@@ -0,0 +1,47 @@
+package platform
+
+import "testing"
+
+func TestForMapsSupportedTargets(t *testing.T) {
+	tests := []struct {
+		goos, goarch, wantOS, wantArch, wantShell string
+	}{
+		{"darwin", "arm64", "macos", "arm64", "bash"},
+		{"windows", "amd64", "windows", "x64", "powershell"},
+		{"linux", "amd64", "linux", "x64", "bash"},
+	}
+	for _, test := range tests {
+		got := For(test.goos, test.goarch)
+		if got.OS != test.wantOS || got.Arch != test.wantArch || got.Shell != test.wantShell {
+			t.Errorf("For(%q, %q) = %#v", test.goos, test.goarch, got)
+		}
+	}
+}
+
+func TestResolveHomeWindowsPrecedence(t *testing.T) {
+	env := map[string]string{
+		"ONEAGENT_HOME": "/override",
+		"USERPROFILE":   `C:\Users\测试 用户`,
+		"HOME":          "/wrong",
+	}
+	if got := ResolveHome(env, "windows"); got != "/override" {
+		t.Fatalf("ONEAGENT_HOME precedence = %q", got)
+	}
+	delete(env, "ONEAGENT_HOME")
+	if got := ResolveHome(env, "windows"); got != `C:\Users\测试 用户` {
+		t.Fatalf("USERPROFILE precedence = %q", got)
+	}
+	delete(env, "USERPROFILE")
+	env["HOMEDRIVE"] = "D:"
+	env["HOMEPATH"] = `\Users\fallback`
+	if got := ResolveHome(env, "windows"); got != `D:\Users\fallback` {
+		t.Fatalf("HOMEDRIVE/HOMEPATH precedence = %q", got)
+	}
+}
+
+func TestResolveHomeExpandsTilde(t *testing.T) {
+	env := map[string]string{"HOME": "/tmp/test-home"}
+	if got := ResolveHome(map[string]string{"ONEAGENT_HOME": "~/oneagent", "HOME": env["HOME"]}, "linux"); got != "/tmp/test-home/oneagent" {
+		t.Fatalf("expanded home = %q", got)
+	}
+}
diff --git a/internal/process/process.go b/internal/process/process.go
new file mode 100644
index 00000000..3548a1af
--- /dev/null
+++ b/internal/process/process.go
@@ -0,0 +1,281 @@
+// Package process provides the narrow subprocess boundary shared by the Go
+// installer and CLI. It accepts argv arrays only and keeps command output
+// bounded before higher layers decide what may be shown to a user.
+package process
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"maps"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+)
+
+const MaxOutputBytes = 1 << 20
+
+type Result struct {
+	Args     []string
+	ExitCode int
+	Stdout   string
+	Stderr   string
+}
+
+type Output struct {
+	Kind   string   `json:"kind"`
+	Args   []string `json:"args,omitempty"`
+	Stream string   `json:"stream,omitempty"`
+	Text   string   `json:"text,omitempty"`
+}
+
+// OutputListener receives each accepted chunk of a command's output.
+//
+// Calls are serialised: stdout and stderr are copied by separate goroutines, so
+// a listener would otherwise be entered concurrently, and every caller would
+// have to synchronise on its own. Implementations may append to a slice or write
+// to a channel without locking.
+type OutputListener func(Output)
+
+type StreamingRunner interface {
+	RunWithOutput(context.Context, []string, map[string]string, time.Duration, OutputListener) (Result, error)
+}
+
+// Runner is deliberately small so install tests can assert exact argv and
+// environment without starting a process.
+type Runner interface {
+	LookPath(string) (string, bool)
+	Run(context.Context, []string, map[string]string, time.Duration) (Result, error)
+}
+
+type OSRunner struct {
+	Env    map[string]string
+	Lookup func(string) (string, bool)
+}
+
+func Current() OSRunner {
+	return OSRunner{Env: environmentFromOS()}
+}
+
+func New(env map[string]string) OSRunner {
+	values := make(map[string]string, len(env))
+	maps.Copy(values, env)
+	return OSRunner{Env: values}
+}
+
+// LookPath resolves a command against this runner's own PATH rather than the
+// OneAgent process PATH. That distinction is what makes a runtime installed
+// into a private directory usable: Run() passes r.Env to the child, so a lookup
+// against the parent process environment would report a managed npm or uv as
+// missing and the installer would keep asking to install it again.
+func (r OSRunner) LookPath(command string) (string, bool) {
+	if r.Lookup != nil {
+		return r.Lookup(command)
+	}
+	search := r.Env["PATH"]
+	if search == "" {
+		search = r.Env["Path"] // Windows callers may carry the native casing.
+	}
+	if search == "" || search == os.Getenv("PATH") {
+		path, err := exec.LookPath(command)
+		return path, err == nil
+	}
+	return lookPathIn(search, command)
+}
+
+// lookPathIn mirrors exec.LookPath's directory walk against an explicit search
+// path. exec.LookPath itself always reads the process environment, so an
+// injected PATH cannot be honored through it.
+func lookPathIn(search, command string) (string, bool) {
+	if command == "" {
+		return "", false
+	}
+	if strings.ContainsAny(command, `/\`) {
+		if executable(command) {
+			return command, true
+		}
+		return "", false
+	}
+	for _, directory := range filepath.SplitList(search) {
+		if directory == "" {
+			directory = "."
+		}
+		for _, candidate := range commandNames(command) {
+			path := filepath.Join(directory, candidate)
+			if executable(path) {
+				return path, true
+			}
+		}
+	}
+	return "", false
+}
+
+// commandNames expands a bare command to the Windows executable extensions. On
+// other platforms the command name is used as given.
+func commandNames(command string) []string {
+	if runtime.GOOS != "windows" {
+		return []string{command}
+	}
+	if filepath.Ext(command) != "" {
+		return []string{command}
+	}
+	extensions := os.Getenv("PATHEXT")
+	if extensions == "" {
+		extensions = ".COM;.EXE;.BAT;.CMD"
+	}
+	names := make([]string, 0, 5)
+	for _, extension := range filepath.SplitList(extensions) {
+		if extension = strings.TrimSpace(extension); extension != "" {
+			names = append(names, command+strings.ToLower(extension))
+		}
+	}
+	return append(names, command)
+}
+
+func executable(path string) bool {
+	info, err := os.Stat(path)
+	if err != nil || info.IsDir() {
+		return false
+	}
+	if runtime.GOOS == "windows" {
+		return true
+	}
+	return info.Mode().Perm()&0o111 != 0
+}
+
+func (r OSRunner) Run(ctx context.Context, argv []string, overrides map[string]string, timeout time.Duration) (Result, error) {
+	return r.RunWithOutput(ctx, argv, overrides, timeout, nil)
+}
+
+func (r OSRunner) RunWithOutput(ctx context.Context, argv []string, overrides map[string]string, timeout time.Duration, listener OutputListener) (Result, error) {
+	result := Result{Args: append([]string(nil), argv...), ExitCode: -1}
+	if len(argv) == 0 || strings.TrimSpace(argv[0]) == "" {
+		return result, fmt.Errorf("process argv must not be empty")
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	runContext := ctx
+	var cancel context.CancelFunc
+	if timeout > 0 {
+		runContext, cancel = context.WithTimeout(ctx, timeout)
+		defer cancel()
+	}
+	command := exec.CommandContext(runContext, argv[0], argv[1:]...)
+	command.Env = mergeEnvironment(r.Env, overrides)
+	stdout := &boundedBuffer{limit: MaxOutputBytes}
+	stderr := &boundedBuffer{limit: MaxOutputBytes}
+	var streamLock sync.Mutex
+	command.Stdout = &streamWriter{stream: "stdout", buffer: stdout, listener: listener, mu: &streamLock}
+	command.Stderr = &streamWriter{stream: "stderr", buffer: stderr, listener: listener, mu: &streamLock}
+	err := command.Run()
+	result.Stdout = stdout.String()
+	result.Stderr = stderr.String()
+	if command.ProcessState != nil {
+		result.ExitCode = command.ProcessState.ExitCode()
+	}
+	if runErr := runContext.Err(); runErr != nil {
+		return result, runErr
+	}
+	if err != nil {
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			result.ExitCode = exitErr.ExitCode()
+			return result, nil
+		}
+		return result, err
+	}
+	if result.ExitCode < 0 {
+		result.ExitCode = 0
+	}
+	return result, nil
+}
+
+type streamWriter struct {
+	stream   string
+	buffer   *boundedBuffer
+	listener OutputListener
+	// Shared by the stdout and stderr writers of one command, so a listener sees
+	// one chunk at a time. Each writer has its own buffer, but a lock per writer
+	// would not serialise anything — the two goroutines would take different
+	// locks and still enter the listener together.
+	mu *sync.Mutex
+}
+
+func (w *streamWriter) Write(data []byte) (int, error) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	before := w.buffer.buffer.Len()
+	n, err := w.buffer.Write(data)
+	accepted := w.buffer.buffer.Len() - before
+	if w.listener != nil && accepted > 0 {
+		w.listener(Output{Kind: "output", Stream: w.stream, Text: string(data[:accepted])})
+	}
+	return n, err
+}
+
+type boundedBuffer struct {
+	buffer    bytes.Buffer
+	limit     int
+	truncated bool
+}
+
+func (b *boundedBuffer) Write(data []byte) (int, error) {
+	if b.limit <= 0 {
+		return len(data), nil
+	}
+	remaining := b.limit - b.buffer.Len()
+	if remaining <= 0 {
+		b.truncated = true
+		return len(data), nil
+	}
+	if len(data) > remaining {
+		_, _ = b.buffer.Write(data[:remaining])
+		b.truncated = true
+		return len(data), nil
+	}
+	_, _ = b.buffer.Write(data)
+	return len(data), nil
+}
+
+func (b *boundedBuffer) String() string {
+	value := b.buffer.String()
+	if b.truncated {
+		value += "\n[output truncated]"
+	}
+	return value
+}
+
+func mergeEnvironment(base, overrides map[string]string) []string {
+	values := make(map[string]string, len(base)+len(overrides))
+	maps.Copy(values, base)
+	maps.Copy(values, overrides)
+	keys := make([]string, 0, len(values))
+	for key := range values {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	result := make([]string, 0, len(keys))
+	for _, key := range keys {
+		result = append(result, key+"="+values[key])
+	}
+	return result
+}
+
+func environmentFromOS() map[string]string {
+	values := make(map[string]string)
+	for _, entry := range os.Environ() {
+		key, value, ok := strings.Cut(entry, "=")
+		if ok {
+			values[key] = value
+		}
+	}
+	return values
+}
+
+var _ io.Writer = (*boundedBuffer)(nil)
diff --git a/internal/process/process_test.go b/internal/process/process_test.go
new file mode 100644
index 00000000..7f9d37d3
--- /dev/null
+++ b/internal/process/process_test.go
@@ -0,0 +1,186 @@
+package process
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestProcessHelper(t *testing.T) {
+	if os.Getenv("ONEAGENT_PROCESS_HELPER") != "1" {
+		return
+	}
+	if os.Getenv("ONEAGENT_PROCESS_EXIT") == "1" {
+		os.Stderr.WriteString("helper stderr")
+		os.Exit(7)
+	}
+	if os.Getenv("ONEAGENT_PROCESS_WAIT") == "1" {
+		// Long enough that the caller's deadline always fires first; the runner
+		// kills this process, so the sleep never runs to completion.
+		<-time.After(10 * time.Second)
+	}
+	// Interleaves both streams so the runner's stdout and stderr copiers are
+	// active at the same time. Real installs look like this — npm reports progress
+	// on stderr while printing results on stdout.
+	if os.Getenv("ONEAGENT_PROCESS_BOTH_STREAMS") == "1" {
+		for index := 0; index < 50; index++ {
+			os.Stdout.WriteString("o")
+			os.Stderr.WriteString("e")
+		}
+		os.Exit(0)
+	}
+	os.Stdout.WriteString(os.Getenv("ONEAGENT_PROCESS_VALUE"))
+	os.Exit(0)
+}
+
+// helperTimeout is generous on purpose. These cases re-exec the test binary as
+// a helper process, and a race-instrumented binary needs well over a second to
+// start; a tight budget here fails the run for timing rather than behavior.
+// Cases that assert timeout handling set their own short deadline.
+const helperTimeout = 60 * time.Second
+
+func helperRunner(t *testing.T) OSRunner {
+	t.Helper()
+	path, err := os.Executable()
+	if err != nil {
+		t.Fatal(err)
+	}
+	/* These cases re-exec the test binary as the helper process, so under `go test
+	   -cover` the child inherits the coverage instrumentation. Without a place to
+	   write its profile it prints "warning: GOCOVERDIR not set" to stderr, which
+	   lands in the captured output and in the listener — failing assertions about
+	   what the command produced for a reason that has nothing to do with the
+	   runner. Giving the child a scratch directory keeps its stderr its own. */
+	runner := New(map[string]string{
+		"ONEAGENT_PROCESS_HELPER": "1",
+		"GOCOVERDIR":              t.TempDir(),
+	})
+	runner.Lookup = func(command string) (string, bool) {
+		if command == "helper" {
+			return path, true
+		}
+		return "", false
+	}
+	return runner
+}
+
+func TestOSRunnerUsesArgvAndMergesEnvironment(t *testing.T) {
+	runner := helperRunner(t)
+	result, err := runner.Run(context.Background(), []string{os.Args[0], "-test.run=TestProcessHelper"}, map[string]string{
+		"ONEAGENT_PROCESS_VALUE": "safe-value",
+	}, helperTimeout)
+	if err != nil || result.ExitCode != 0 || result.Stdout != "safe-value" {
+		t.Fatalf("process result = %#v, err=%v", result, err)
+	}
+	if len(result.Args) != 2 || result.Args[1] != "-test.run=TestProcessHelper" {
+		t.Fatalf("argv was changed: %#v", result.Args)
+	}
+}
+
+func TestOSRunnerStreamsOutputWithoutChangingResult(t *testing.T) {
+	runner := helperRunner(t)
+	outputs := make([]Output, 0)
+	result, err := runner.RunWithOutput(context.Background(), []string{os.Args[0], "-test.run=TestProcessHelper"}, map[string]string{
+		"ONEAGENT_PROCESS_VALUE": "stream-value",
+	}, helperTimeout, func(output Output) { outputs = append(outputs, output) })
+	if err != nil || result.ExitCode != 0 || result.Stdout != "stream-value" {
+		t.Fatalf("streamed process result = %#v, err=%v", result, err)
+	}
+	if len(outputs) != 1 || outputs[0].Kind != "output" || outputs[0].Stream != "stdout" || outputs[0].Text != "stream-value" {
+		t.Fatalf("streamed outputs = %#v", outputs)
+	}
+}
+
+// The listener here appends without locking, exactly as the install runtime's
+// does (internal/app/install.go redacts and forwards). stdout and stderr are
+// copied by separate goroutines, so without serialisation inside the runner this
+// is a data race in production, not just in a test — it surfaces whenever a
+// command writes to both streams, which npm does on every install.
+func TestOSRunnerSerialisesListenerAcrossStreams(t *testing.T) {
+	runner := helperRunner(t)
+	outputs := make([]Output, 0)
+	result, err := runner.RunWithOutput(context.Background(), []string{os.Args[0], "-test.run=TestProcessHelper"}, map[string]string{
+		"ONEAGENT_PROCESS_BOTH_STREAMS": "1",
+	}, helperTimeout, func(output Output) { outputs = append(outputs, output) })
+	if err != nil || result.ExitCode != 0 {
+		t.Fatalf("interleaved process result = %#v, err=%v", result, err)
+	}
+	var stdout, stderr int
+	for _, output := range outputs {
+		switch output.Stream {
+		case "stdout":
+			stdout += len(output.Text)
+		case "stderr":
+			stderr += len(output.Text)
+		}
+	}
+	// Both streams have to reach the listener; asserting only the total would
+	// pass even if one stream's chunks were being dropped.
+	if stdout != 50 || stderr != 50 {
+		t.Fatalf("streamed %d stdout and %d stderr bytes, want 50 of each", stdout, stderr)
+	}
+}
+
+func TestOSRunnerReturnsExitCodeAndCapturesOutput(t *testing.T) {
+	runner := helperRunner(t)
+	result, err := runner.Run(context.Background(), []string{os.Args[0], "-test.run=TestProcessHelper"}, map[string]string{
+		"ONEAGENT_PROCESS_EXIT": "1",
+	}, helperTimeout)
+	if err != nil || result.ExitCode != 7 || result.Stderr != "helper stderr" {
+		t.Fatalf("non-zero result = %#v, err=%v", result, err)
+	}
+}
+
+func TestOSRunnerHonorsCancellationAndRejectsEmptyArgv(t *testing.T) {
+	runner := helperRunner(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err := runner.Run(ctx, []string{os.Args[0], "-test.run=TestProcessHelper"}, nil, helperTimeout)
+	if err == nil || err != context.Canceled {
+		t.Fatalf("cancelled process error = %v", err)
+	}
+	if _, err := runner.Run(context.Background(), nil, nil, helperTimeout); err == nil {
+		t.Fatal("empty argv unexpectedly succeeded")
+	}
+}
+
+func TestOSRunnerHonorsTimeout(t *testing.T) {
+	runner := helperRunner(t)
+	_, err := runner.Run(context.Background(), []string{os.Args[0], "-test.run=TestProcessHelper"}, map[string]string{
+		"ONEAGENT_PROCESS_WAIT": "1",
+	}, 10*time.Millisecond)
+	if err == nil || !strings.Contains(err.Error(), "deadline exceeded") {
+		t.Fatalf("timeout error = %v", err)
+	}
+}
+
+func TestOSRunnerLookPathCanBeInjected(t *testing.T) {
+	runner := helperRunner(t)
+	if path, ok := runner.LookPath("helper"); !ok || path == "" {
+		t.Fatalf("injected lookup = %q, %v", path, ok)
+	}
+	if _, ok := runner.LookPath("missing"); ok {
+		t.Fatal("missing command unexpectedly found")
+	}
+}
+
+func TestBoundedBufferDoesNotBlockProducer(t *testing.T) {
+	buffer := &boundedBuffer{limit: 4}
+	if written, err := buffer.Write([]byte("abcdef")); err != nil || written != 6 {
+		t.Fatalf("bounded write = %d, %v", written, err)
+	}
+	if got := buffer.String(); got != "abcd\n[output truncated]" {
+		t.Fatalf("bounded output = %q", got)
+	}
+}
+
+func TestOSRunnerUsesExecutableWithoutShell(t *testing.T) {
+	runner := helperRunner(t)
+	result, err := runner.Run(context.Background(), []string{exec.Command("true").Path}, nil, helperTimeout)
+	if err != nil || result.ExitCode != 0 {
+		t.Fatalf("direct executable result = %#v, err=%v", result, err)
+	}
+}
diff --git a/internal/profile/binding.go b/internal/profile/binding.go
new file mode 100644
index 00000000..84da064e
--- /dev/null
+++ b/internal/profile/binding.go
@@ -0,0 +1,159 @@
+package profile
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+)
+
+type AgentBinding struct {
+	SchemaVersion int    `json:"schema_version"`
+	AgentID       string `json:"agent_id"`
+	Provider      string `json:"provider"`
+	BaseURL       string `json:"base_url"`
+	Model         string `json:"model"`
+	ProfileRef    string `json:"profile_ref"`
+	CreatedAt     string `json:"created_at"`
+	UpdatedAt     string `json:"updated_at"`
+}
+
+type BindingWriteRequest struct {
+	Provider   string
+	BaseURL    string
+	Model      string
+	ProfileRef string
+}
+
+type storedBinding struct {
+	SchemaVersion int    `json:"schema_version"`
+	AgentID       string `json:"agent_id"`
+	Provider      string `json:"provider"`
+	BaseURL       string `json:"base_url"`
+	Model         string `json:"model"`
+	ProfileRef    string `json:"profile_ref"`
+	CreatedAt     string `json:"created_at"`
+	UpdatedAt     string `json:"updated_at"`
+}
+
+func (s Store) AgentsPath() string {
+	return filepath.Join(s.Root(), "agents")
+}
+
+func (s Store) AgentBindingPath(agentID string) (string, error) {
+	if err := ValidateID(agentID); err != nil {
+		return "", oneerrors.New(oneerrors.InvalidRequest, fmt.Sprintf("Invalid Agent ID: %s", agentID))
+	}
+	return filepath.Join(s.AgentsPath(), agentID+".json"), nil
+}
+
+func (s Store) ReadAgentBinding(agentID string) (*AgentBinding, error) {
+	path, err := s.AgentBindingPath(agentID)
+	if err != nil {
+		return nil, err
+	}
+	data, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("cannot read Agent binding for %s: %w", agentID, err)
+	}
+	var stored storedBinding
+	if err := json.Unmarshal(data, &stored); err != nil {
+		return nil, fmt.Errorf("Agent binding for %s is corrupt", agentID)
+	}
+	if stored.SchemaVersion != 1 {
+		return nil, fmt.Errorf("Unsupported Agent binding schema for %s", agentID)
+	}
+	if stored.AgentID != agentID {
+		return nil, fmt.Errorf("Agent binding for %s is corrupt", agentID)
+	}
+	return &AgentBinding{
+		SchemaVersion: stored.SchemaVersion,
+		AgentID:       stored.AgentID,
+		Provider:      stored.Provider,
+		BaseURL:       stored.BaseURL,
+		Model:         stored.Model,
+		ProfileRef:    stored.ProfileRef,
+		CreatedAt:     stored.CreatedAt,
+		UpdatedAt:     stored.UpdatedAt,
+	}, nil
+}
+
+func (s Store) ListAgentBindings() map[string]AgentBinding {
+	entries, err := os.ReadDir(s.AgentsPath())
+	if err != nil {
+		return map[string]AgentBinding{}
+	}
+	result := make(map[string]AgentBinding)
+	ids := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") {
+			continue
+		}
+		id := strings.TrimSuffix(entry.Name(), ".json")
+		if ValidateID(id) != nil {
+			continue
+		}
+		ids = append(ids, id)
+	}
+	sort.Strings(ids)
+	for _, id := range ids {
+		binding, err := s.ReadAgentBinding(id)
+		if err == nil && binding != nil {
+			result[id] = *binding
+		}
+	}
+	return result
+}
+
+func (s Store) WriteAgentBinding(ctx context.Context, agentID string, request BindingWriteRequest) (AgentBinding, error) {
+	if err := requestContext(ctx); err != nil {
+		return AgentBinding{}, err
+	}
+	path, err := s.AgentBindingPath(agentID)
+	if err != nil {
+		return AgentBinding{}, err
+	}
+	if strings.TrimSpace(request.Provider) == "" || strings.TrimSpace(request.BaseURL) == "" || strings.TrimSpace(request.Model) == "" {
+		return AgentBinding{}, oneerrors.New(oneerrors.InvalidRequest, "Agent binding requires provider, base URL, and model")
+	}
+	existing, _ := s.ReadAgentBinding(agentID)
+	now := s.clock().UTC().Format(time.RFC3339)
+	profileRef := request.ProfileRef
+	created := now
+	if existing != nil {
+		if profileRef == "" {
+			profileRef = existing.ProfileRef
+		}
+		if existing.CreatedAt != "" {
+			created = existing.CreatedAt
+		}
+	}
+	stored := storedBinding{
+		SchemaVersion: 1,
+		AgentID:       agentID,
+		Provider:      request.Provider,
+		BaseURL:       request.BaseURL,
+		Model:         request.Model,
+		ProfileRef:    profileRef,
+		CreatedAt:     created,
+		UpdatedAt:     now,
+	}
+	data, err := json.MarshalIndent(stored, "", "  ")
+	if err != nil {
+		return AgentBinding{}, oneerrors.New(oneerrors.ConfigWriteFailed, "Cannot encode Agent binding")
+	}
+	data = append(data, '\n')
+	if _, err := s.filesystem().AtomicWrite(ctx, path, data, false); err != nil {
+		return AgentBinding{}, err
+	}
+	return AgentBinding(stored), nil
+}
diff --git a/internal/profile/binding_test.go b/internal/profile/binding_test.go
new file mode 100644
index 00000000..c2333e2e
--- /dev/null
+++ b/internal/profile/binding_test.go
@@ -0,0 +1,92 @@
+package profile
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestAgentBindingWriteReadAndPreserveProfileReference(t *testing.T) {
+	store := testStore(t, t.TempDir(), "linux")
+	binding, err := store.WriteAgentBinding(context.Background(), "codex", BindingWriteRequest{
+		Provider:   "ppio",
+		BaseURL:    "https://api.ppio.com/responses",
+		Model:      "model-a",
+		ProfileRef: "team",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if binding.AgentID != "codex" || binding.ProfileRef != "team" {
+		t.Fatalf("binding = %#v", binding)
+	}
+	updated, err := store.WriteAgentBinding(context.Background(), "codex", BindingWriteRequest{
+		Provider: "novita",
+		BaseURL:  "https://api.novita.ai/openai",
+		Model:    "model-b",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if updated.ProfileRef != "team" || updated.CreatedAt != binding.CreatedAt || updated.UpdatedAt == "" {
+		t.Fatalf("updated binding = %#v", updated)
+	}
+	read, err := store.ReadAgentBinding("codex")
+	if err != nil || read == nil || read.Provider != "novita" {
+		t.Fatalf("ReadAgentBinding() = %#v, %v", read, err)
+	}
+	wire, err := json.Marshal(read)
+	if err != nil || strings.Contains(string(wire), "api_key") || strings.Contains(string(wire), "secret") {
+		t.Fatalf("binding projection leaked unknown fields: %s (%v)", wire, err)
+	}
+	assertProfileMode(t, func() string { path, _ := store.AgentBindingPath("codex"); return path }(), 0o600)
+}
+
+func TestAgentBindingListSkipsCorruptAndInvalidFiles(t *testing.T) {
+	store := testStore(t, t.TempDir(), "linux")
+	if err := os.MkdirAll(store.AgentsPath(), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	fixtures := map[string]string{
+		"codex.json":    "{",
+		"claude.json":   `{"schema_version":9,"agent_id":"claude"}`,
+		"Bad-Name.json": `{"schema_version":1,"agent_id":"Bad-Name"}`,
+		"openai.json":   `{"schema_version":1,"agent_id":"other","provider":"ppio"}`,
+	}
+	for name, content := range fixtures {
+		if err := os.WriteFile(filepath.Join(store.AgentsPath(), name), []byte(content), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if _, err := store.WriteAgentBinding(context.Background(), "opencode", BindingWriteRequest{Provider: "ppio", BaseURL: "https://api.ppio.com/openai", Model: "m"}); err != nil {
+		t.Fatal(err)
+	}
+	bindings := store.ListAgentBindings()
+	if len(bindings) != 1 || bindings["opencode"].Model != "m" {
+		t.Fatalf("bindings = %#v", bindings)
+	}
+	if _, err := store.ReadAgentBinding("../escape"); err == nil {
+		t.Fatal("traversal Agent ID unexpectedly accepted")
+	}
+}
+
+func TestAgentBindingRejectsInvalidInputAndHonorsCancellation(t *testing.T) {
+	store := testStore(t, t.TempDir(), "linux")
+	for _, request := range []BindingWriteRequest{{Provider: "", BaseURL: "x", Model: "m"}, {Provider: "p", BaseURL: "", Model: "m"}, {Provider: "p", BaseURL: "x", Model: ""}} {
+		if _, err := store.WriteAgentBinding(context.Background(), "codex", request); err == nil {
+			t.Errorf("invalid binding %#v succeeded", request)
+		}
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if _, err := store.WriteAgentBinding(ctx, "codex", BindingWriteRequest{Provider: "p", BaseURL: "x", Model: "m"}); err == nil {
+		t.Fatal("cancelled binding write succeeded")
+	}
+	if got := store.ListAgentBindings(); !reflect.DeepEqual(got, map[string]AgentBinding{}) {
+		t.Fatalf("cancelled write changed bindings = %#v", got)
+	}
+}
diff --git a/internal/profile/migration_test.go b/internal/profile/migration_test.go
new file mode 100644
index 00000000..f9672d15
--- /dev/null
+++ b/internal/profile/migration_test.go
@@ -0,0 +1,86 @@
+package profile
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+func TestLoadActiveMigratesV1WithBackupAndPublicProjection(t *testing.T) {
+	home := t.TempDir()
+	store := testStore(t, home, "linux")
+	if err := os.MkdirAll(store.Root(), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	legacy := `{"schema_version":1,"provider":"ppio","base_url":"https://api.ppio.com/openai","model":"legacy-model","config_mode":"provider","agent_ids":["opencode","codex"],"activated_at":"2026-07-22T00:00:00Z","api_key":"must-not-copy"}`
+	if err := os.WriteFile(store.PointerPath(), []byte(legacy), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	result := store.LoadActiveContext(context.Background())
+	if result.Error != "" || result.Profile == nil || result.ID != "default" {
+		t.Fatalf("migration result = %#v", result)
+	}
+	if result.Profile.CreatedAt != "2026-07-22T00:00:00Z" || result.Environment["model"] != "legacy-model" {
+		t.Fatalf("migrated projection = %#v", result)
+	}
+	var pointer map[string]any
+	data, err := os.ReadFile(store.PointerPath())
+	if err != nil || json.Unmarshal(data, &pointer) != nil || pointer["active"] != "default" || pointer["schema_version"] != float64(2) {
+		t.Fatalf("migrated pointer = %s, %v", data, err)
+	}
+	profilePath, _ := store.ProfilePath("default")
+	profileData, err := os.ReadFile(profilePath)
+	if err != nil || strings.Contains(string(profileData), "must-not-copy") {
+		t.Fatalf("migrated profile = %s, %v", profileData, err)
+	}
+	backups, _ := filepath.Glob(store.PointerPath() + ".backup-*")
+	if len(backups) != 1 {
+		t.Fatalf("legacy backups = %v", backups)
+	}
+	if listed := store.List(); len(listed) != 1 || listed[0].ID != "default" {
+		t.Fatalf("migrated list = %#v", listed)
+	}
+	// A second read follows the v2 pointer and does not create another backup.
+	if result := store.LoadActive(); result.Error != "" || result.ID != "default" {
+		t.Fatalf("second migrated read = %#v", result)
+	}
+	backups, _ = filepath.Glob(store.PointerPath() + ".backup-*")
+	if len(backups) != 1 {
+		t.Fatalf("second read changed backups = %v", backups)
+	}
+}
+
+func TestLegacyMigrationFailureLeavesOriginalPointer(t *testing.T) {
+	home := t.TempDir()
+	filesystem := securefs.New(securefs.Options{
+		OS: "linux",
+		Secure: func(path string, directory bool) error {
+			if directory && strings.HasSuffix(path, "profiles") {
+				return oneerrors.New(oneerrors.ConfigWriteFailed, "profiles are read-only")
+			}
+			return nil
+		},
+	})
+	store := NewStoreWithDependencies(home, "linux", filesystem, fixedProfileClock)
+	if err := os.MkdirAll(store.Root(), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	original := []byte(`{"schema_version":1,"provider":"ppio","model":"m"}`)
+	if err := os.WriteFile(store.PointerPath(), original, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	result := store.LoadActive()
+	if result.Profile != nil || !strings.Contains(result.Error, "Cannot migrate legacy profile") {
+		t.Fatalf("migration failure = %#v", result)
+	}
+	data, err := os.ReadFile(store.PointerPath())
+	if err != nil || string(data) != string(original) {
+		t.Fatalf("original pointer changed: %s, %v", data, err)
+	}
+}
diff --git a/internal/profile/store.go b/internal/profile/store.go
new file mode 100644
index 00000000..dc6c54ce
--- /dev/null
+++ b/internal/profile/store.go
@@ -0,0 +1,409 @@
+// Package profile reads and writes the on-disk profile store without exposing
+// secret contents. Agent configuration and installation remain separate.
+package profile
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+var profileIDPattern = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]{0,63}$`)
+
+type Store struct {
+	Home string
+	OS   string
+	FS   *securefs.Store
+	Now  func() time.Time
+	mu   *sync.Mutex
+}
+
+type Profile struct {
+	SchemaVersion int
+	ID            string
+	Label         string
+	Provider      string
+	BaseURL       *string
+	Model         *string
+	ConfigMode    string
+	AgentIDs      []string
+	CreatedAt     string
+	ActivatedAt   *string
+	HasKey        bool
+}
+
+type Summary struct {
+	ID          string
+	Label       string
+	Provider    string
+	BaseURL     *string
+	Model       *string
+	AgentIDs    []string
+	ActivatedAt *string
+	HasKey      bool
+}
+
+type ActiveResult struct {
+	Profile     *Profile
+	Environment map[string]any
+	ID          string
+	Error       string
+}
+
+type storedProfile struct {
+	SchemaVersion int      `json:"schema_version"`
+	ID            string   `json:"id"`
+	Label         string   `json:"label"`
+	Provider      string   `json:"provider"`
+	BaseURL       *string  `json:"base_url"`
+	Model         *string  `json:"model"`
+	ConfigMode    string   `json:"config_mode"`
+	AgentIDs      []string `json:"agent_ids"`
+	CreatedAt     string   `json:"created_at"`
+	ActivatedAt   *string  `json:"activated_at"`
+}
+
+// activePointer is deliberately a struct rather than a map so the persisted
+// field order stays stable across activations.
+type activePointer struct {
+	SchemaVersion int    `json:"schema_version"`
+	Active        string `json:"active"`
+}
+
+func NewStore(home, osID string) Store {
+	filesystem := securefs.New(securefs.Options{OS: osID})
+	return Store{Home: home, OS: osID, FS: &filesystem, Now: time.Now, mu: &sync.Mutex{}}
+}
+
+func NewStoreWithDependencies(home, osID string, filesystem securefs.Store, now func() time.Time) Store {
+	if now == nil {
+		now = time.Now
+	}
+	return Store{Home: home, OS: osID, FS: &filesystem, Now: now, mu: &sync.Mutex{}}
+}
+
+func ValidateID(id string) error {
+	if !profileIDPattern.MatchString(id) {
+		return oneerrors.New(oneerrors.InvalidRequest, "Profile ID must start with a lowercase letter or digit and use only lowercase letters, digits, '-' or '_'")
+	}
+	return nil
+}
+
+func (s Store) Root() string {
+	return filepath.Join(s.Home, ".oneagent")
+}
+
+func (s Store) PointerPath() string {
+	return filepath.Join(s.Root(), "profile.json")
+}
+
+func (s Store) ProfilesPath() string {
+	return filepath.Join(s.Root(), "profiles")
+}
+
+func (s Store) ProfilePath(id string) (string, error) {
+	if err := ValidateID(id); err != nil {
+		return "", err
+	}
+	return filepath.Join(s.ProfilesPath(), id+".json"), nil
+}
+
+func (s Store) SecretPath(id string) (string, error) {
+	if err := ValidateID(id); err != nil {
+		return "", err
+	}
+	suffix := "env"
+	if s.OS == "windows" {
+		suffix = "env.ps1"
+	}
+	return filepath.Join(s.Root(), "secrets", id+"."+suffix), nil
+}
+
+func (s Store) List() []Profile {
+	entries, err := os.ReadDir(s.ProfilesPath())
+	if err != nil {
+		return []Profile{}
+	}
+	profiles := make([]Profile, 0, len(entries))
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") {
+			continue
+		}
+		path := filepath.Join(s.ProfilesPath(), entry.Name())
+		data, err := os.ReadFile(path)
+		if err != nil {
+			continue
+		}
+		profile, err := decodeStored(data)
+		if err != nil || ValidateID(profile.ID) != nil {
+			continue
+		}
+		secret, err := s.SecretPath(profile.ID)
+		if err == nil {
+			_, statErr := os.Stat(secret)
+			profile.HasKey = statErr == nil
+		}
+		profiles = append(profiles, profile)
+	}
+	return profiles
+}
+
+func (s Store) LoadActive() ActiveResult {
+	return s.LoadActiveContext(context.Background())
+}
+
+func (s Store) LoadActiveContext(ctx context.Context) ActiveResult {
+	if err := requestContext(ctx); err != nil {
+		return ActiveResult{Error: err.Error()}
+	}
+	data, err := os.ReadFile(s.PointerPath())
+	if os.IsNotExist(err) {
+		return ActiveResult{}
+	}
+	if err != nil {
+		return ActiveResult{Error: err.Error()}
+	}
+	var pointer map[string]any
+	if err := json.Unmarshal(data, &pointer); err != nil {
+		return ActiveResult{Error: err.Error()}
+	}
+	schema, ok := integerField(pointer["schema_version"])
+	if !ok {
+		return ActiveResult{Error: "Unsupported environment profile schema"}
+	}
+	if schema == 1 {
+		profile := migrateLegacy(pointer)
+		profile, err = s.persistLegacy(ctx, profile)
+		if err != nil {
+			return ActiveResult{Error: fmt.Sprintf("Cannot migrate legacy profile: %v", err)}
+		}
+		return ActiveResult{Profile: &profile, Environment: profile.environment(), ID: profile.ID}
+	}
+	if schema != 2 {
+		return ActiveResult{Error: "Unsupported environment profile schema"}
+	}
+	active, ok := pointer["active"].(string)
+	if !ok {
+		return ActiveResult{Error: "Unsupported environment profile schema"}
+	}
+	if err := ValidateID(active); err != nil {
+		return ActiveResult{Error: err.Error()}
+	}
+	result := ActiveResult{ID: active}
+	path, err := s.ProfilePath(active)
+	if err != nil {
+		result.Error = err.Error()
+		return result
+	}
+	data, err = os.ReadFile(path)
+	if os.IsNotExist(err) {
+		result.Error = fmt.Sprintf("Profile %s is missing", active)
+		return result
+	}
+	if err != nil {
+		result.Error = err.Error()
+		return result
+	}
+	profile, err := decodeStored(data)
+	if err != nil {
+		result.Error = fmt.Sprintf("Profile %s is corrupt", active)
+		return result
+	}
+	if profile.ID == "" || profile.ID != active {
+		result.Error = fmt.Sprintf("Profile %s is corrupt", active)
+		return result
+	}
+	if err := ValidateID(profile.ID); err != nil {
+		result.Error = err.Error()
+		return result
+	}
+	result.Profile = &profile
+	result.Environment = profile.environment()
+	return result
+}
+
+func (s Store) persistLegacy(ctx context.Context, profile Profile) (Profile, error) {
+	if s.mu != nil {
+		s.mu.Lock()
+		defer s.mu.Unlock()
+	}
+	stored := storedProfile{
+		SchemaVersion: 2,
+		ID:            profile.ID,
+		Label:         profile.Label,
+		Provider:      profile.Provider,
+		BaseURL:       profile.BaseURL,
+		Model:         profile.Model,
+		ConfigMode:    profile.ConfigMode,
+		AgentIDs:      cloneStrings(profile.AgentIDs),
+		CreatedAt:     profile.CreatedAt,
+		ActivatedAt:   profile.ActivatedAt,
+	}
+	if stored.CreatedAt == "" {
+		stored.CreatedAt = s.clock().UTC().Format(time.RFC3339)
+		profile.CreatedAt = stored.CreatedAt
+	}
+	if stored.ActivatedAt == nil {
+		stored.ActivatedAt = stringPointer(stored.CreatedAt)
+		profile.ActivatedAt = stored.ActivatedAt
+	}
+	if err := s.writeStored(ctx, stored); err != nil {
+		return Profile{}, err
+	}
+	pointer := activePointer{SchemaVersion: 2, Active: stored.ID}
+	data, err := json.MarshalIndent(pointer, "", "  ")
+	if err != nil {
+		return Profile{}, writeError("Cannot encode migrated profile pointer: %v", err)
+	}
+	data = append(data, '\n')
+	_, err = s.filesystem().AtomicWrite(ctx, s.PointerPath(), data, false)
+	if err != nil {
+		return Profile{}, err
+	}
+	return profile, nil
+}
+
+func (p Profile) Summary() Summary {
+	return Summary{
+		ID:          p.ID,
+		Label:       valueOr(p.Label, p.ID),
+		Provider:    p.Provider,
+		BaseURL:     p.BaseURL,
+		Model:       p.Model,
+		AgentIDs:    cloneStrings(p.AgentIDs),
+		ActivatedAt: p.ActivatedAt,
+		HasKey:      p.HasKey,
+	}
+}
+
+func (p Profile) environment() map[string]any {
+	return map[string]any{
+		"schema_version": p.SchemaVersion,
+		"id":             p.ID,
+		"label":          p.Label,
+		"provider":       p.Provider,
+		"base_url":       optionalStringValue(p.BaseURL),
+		"model":          optionalStringValue(p.Model),
+		"config_mode":    p.ConfigMode,
+		"agent_ids":      cloneStrings(p.AgentIDs),
+		"created_at":     p.CreatedAt,
+		"activated_at":   optionalStringValue(p.ActivatedAt),
+	}
+}
+
+func decodeStored(data []byte) (Profile, error) {
+	var stored storedProfile
+	if err := json.Unmarshal(data, &stored); err != nil {
+		return Profile{}, err
+	}
+	if stored.ID == "" {
+		return Profile{}, fmt.Errorf("profile has no id")
+	}
+	if stored.SchemaVersion != 2 {
+		return Profile{}, fmt.Errorf("Unsupported profile schema")
+	}
+	return Profile{
+		SchemaVersion: stored.SchemaVersion,
+		ID:            stored.ID,
+		Label:         stored.Label,
+		Provider:      stored.Provider,
+		BaseURL:       stored.BaseURL,
+		Model:         stored.Model,
+		ConfigMode:    stored.ConfigMode,
+		AgentIDs:      cloneStrings(stored.AgentIDs),
+		CreatedAt:     stored.CreatedAt,
+		ActivatedAt:   stored.ActivatedAt,
+	}, nil
+}
+
+func migrateLegacy(pointer map[string]any) Profile {
+	activated, _ := pointer["activated_at"].(string)
+	configMode, _ := pointer["config_mode"].(string)
+	if configMode == "" {
+		configMode = "provider"
+	}
+	return Profile{
+		SchemaVersion: 2,
+		ID:            "default",
+		Label:         "default",
+		Provider:      stringField(pointer["provider"]),
+		BaseURL:       pointerString(pointer["base_url"]),
+		Model:         pointerString(pointer["model"]),
+		ConfigMode:    configMode,
+		AgentIDs:      stringSlice(pointer["agent_ids"]),
+		CreatedAt:     activated,
+		ActivatedAt:   stringPointer(activated),
+	}
+}
+
+func integerField(value any) (int, bool) {
+	number, ok := value.(float64)
+	return int(number), ok && number == float64(int(number))
+}
+
+func stringField(value any) string {
+	valueString, _ := value.(string)
+	return valueString
+}
+
+func pointerString(value any) *string {
+	if value == nil {
+		return nil
+	}
+	valueString, ok := value.(string)
+	if !ok {
+		return nil
+	}
+	return &valueString
+}
+
+func stringPointer(value string) *string {
+	if value == "" {
+		return nil
+	}
+	return &value
+}
+
+func stringSlice(value any) []string {
+	items, ok := value.([]any)
+	if !ok {
+		return []string{}
+	}
+	result := make([]string, 0, len(items))
+	for _, item := range items {
+		if valueString, ok := item.(string); ok {
+			result = append(result, valueString)
+		}
+	}
+	return result
+}
+
+func cloneStrings(values []string) []string {
+	if len(values) == 0 {
+		return []string{}
+	}
+	return append([]string{}, values...)
+}
+
+func optionalStringValue(value *string) any {
+	if value == nil {
+		return nil
+	}
+	return *value
+}
+
+func valueOr(value, fallback string) string {
+	if value == "" {
+		return fallback
+	}
+	return value
+}
diff --git a/internal/profile/store_test.go b/internal/profile/store_test.go
new file mode 100644
index 00000000..30bb557c
--- /dev/null
+++ b/internal/profile/store_test.go
@@ -0,0 +1,158 @@
+package profile
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+)
+
+func writeProfileFixture(t *testing.T, store Store, id, content string) {
+	t.Helper()
+	path, err := store.ProfilePath(id)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestValidateIDAndPathsRejectTraversal(t *testing.T) {
+	store := NewStore(t.TempDir(), "linux")
+	for _, id := range []string{"", "Upper", "-lead", "a" + string(make([]byte, 65)), "../escape", "a/b"} {
+		if err := ValidateID(id); err == nil {
+			t.Errorf("ValidateID(%q) unexpectedly succeeded", id)
+		}
+		if _, err := store.ProfilePath(id); err == nil {
+			t.Errorf("ProfilePath(%q) unexpectedly succeeded", id)
+		}
+	}
+	if got, err := store.SecretPath("team_one"); err != nil || filepath.Base(got) != "team_one.env" {
+		t.Fatalf("SecretPath() = %q, %v", got, err)
+	}
+	if got, err := NewStore(t.TempDir(), "windows").SecretPath("team_one"); err != nil || filepath.Base(got) != "team_one.env.ps1" {
+		t.Fatalf("Windows SecretPath() = %q, %v", got, err)
+	}
+}
+
+func TestEmptyStoreAndStableListProjection(t *testing.T) {
+	store := NewStore(t.TempDir(), "linux")
+	if got := store.List(); len(got) != 0 {
+		t.Fatalf("empty List() = %#v", got)
+	}
+	if result := store.LoadActive(); result.Profile != nil || result.ID != "" || result.Error != "" {
+		t.Fatalf("empty LoadActive() = %#v", result)
+	}
+	writeProfileFixture(t, store, "b-profile", `{"schema_version":2,"id":"b-profile","label":"B","provider":"novita","base_url":null,"model":"m2","config_mode":"provider","agent_ids":["aider"],"created_at":"t2","activated_at":null}`)
+	writeProfileFixture(t, store, "a-profile", `{"schema_version":2,"id":"a-profile","label":"A","provider":"ppio","base_url":"https://api.ppio.com/openai","model":"m1","config_mode":"provider","agent_ids":["codex"],"created_at":"t1","activated_at":"t1"}`)
+	secret, err := store.SecretPath("a-profile")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Dir(secret), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(secret, []byte("export ONEAGENT_API_KEY=hidden\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	profiles := store.List()
+	if len(profiles) != 2 || profiles[0].ID != "a-profile" || profiles[1].ID != "b-profile" || !profiles[0].HasKey || profiles[1].HasKey {
+		t.Fatalf("stable profile list = %#v", profiles)
+	}
+	summary := profiles[0].Summary()
+	if summary.HasKey != true || summary.BaseURL == nil || *summary.BaseURL != "https://api.ppio.com/openai" {
+		t.Fatalf("summary = %#v", summary)
+	}
+}
+
+func TestLoadActiveV2PreservesPointerAndStripsSecrets(t *testing.T) {
+	store := NewStore(t.TempDir(), "linux")
+	writeProfileFixture(t, store, "team", `{"schema_version":2,"id":"team","label":"Team","provider":"ppio","base_url":"https://api.ppio.com/openai","model":"m","config_mode":"provider","agent_ids":["codex"],"created_at":"created","activated_at":"active","api_key":"must-not-escape"}`)
+	if err := os.MkdirAll(store.Root(), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(store.PointerPath(), []byte(`{"schema_version":2,"active":"team"}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	result := store.LoadActive()
+	if result.Error != "" || result.ID != "team" || result.Profile == nil {
+		t.Fatalf("active result = %#v", result)
+	}
+	if result.Environment["api_key"] != nil {
+		t.Fatalf("environment exposed a secret: %#v", result.Environment)
+	}
+	if result.Environment["provider"] != "ppio" || result.Environment["model"] != "m" {
+		t.Fatalf("environment projection = %#v", result.Environment)
+	}
+}
+
+func TestLoadActiveLegacyAndFailures(t *testing.T) {
+	store := NewStore(t.TempDir(), "linux")
+	if err := os.MkdirAll(store.Root(), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	legacy := map[string]any{
+		"schema_version": 1,
+		"provider":       "ppio",
+		"base_url":       "https://api.ppio.com/openai",
+		"model":          "m",
+		"config_mode":    "provider",
+		"agent_ids":      []string{"codex"},
+		"activated_at":   "2026-07-22T00:00:00Z",
+	}
+	data, _ := json.Marshal(legacy)
+	if err := os.WriteFile(store.PointerPath(), data, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	result := store.LoadActive()
+	if result.Error != "" || result.ID != "default" || result.Profile == nil || result.Profile.Provider != "ppio" {
+		t.Fatalf("legacy result = %#v", result)
+	}
+	if result.Profile.CreatedAt != "2026-07-22T00:00:00Z" {
+		t.Fatalf("legacy created_at = %q", result.Profile.CreatedAt)
+	}
+	if err := os.WriteFile(store.PointerPath(), []byte("{"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if result := store.LoadActive(); result.Error == "" || result.Profile != nil {
+		t.Fatalf("invalid JSON result = %#v", result)
+	}
+	if err := os.WriteFile(store.PointerPath(), []byte(`{"schema_version":2,"active":"ghost"}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	result = store.LoadActive()
+	if result.ID != "ghost" || result.Profile != nil || result.Error != "Profile ghost is missing" {
+		t.Fatalf("missing profile result = %#v", result)
+	}
+	writeProfileFixture(t, store, "ghost", `{"schema_version":2,"id":"other"}`)
+	result = store.LoadActive()
+	if result.Profile != nil || result.Error != "Profile ghost is corrupt" {
+		t.Fatalf("mismatched profile result = %#v", result)
+	}
+}
+
+func TestListSkipsCorruptAndSecretContentsNeverEnterSummary(t *testing.T) {
+	store := NewStore(t.TempDir(), "linux")
+	if err := os.MkdirAll(store.ProfilesPath(), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(store.ProfilesPath(), "bad.json"), []byte("{"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(store.ProfilesPath(), "noid.json"), []byte(`{"schema_version":2,"provider":"ppio"}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	writeProfileFixture(t, store, "real", `{"schema_version":2,"id":"real","provider":"ppio","model":"m"}`)
+	profiles := store.List()
+	if len(profiles) != 1 || profiles[0].ID != "real" {
+		t.Fatalf("filtered profiles = %#v", profiles)
+	}
+	if got := profiles[0].Summary().AgentIDs; !reflect.DeepEqual(got, []string{}) {
+		t.Fatalf("summary AgentIDs = %#v, want an empty array", got)
+	}
+}
diff --git a/internal/profile/write.go b/internal/profile/write.go
new file mode 100644
index 00000000..837eb3cf
--- /dev/null
+++ b/internal/profile/write.go
@@ -0,0 +1,406 @@
+package profile
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"sort"
+	"strings"
+	"time"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/provider"
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+type SaveRequest struct {
+	ID         string
+	Label      string
+	Provider   string
+	BaseURL    string
+	APIKey     string
+	Model      string
+	ConfigMode string
+	AgentIDs   []string
+}
+
+type ActiveRequest struct {
+	ProfileID string
+	Agents    []string
+	Configure bool
+	Provider  string
+	BaseURL   string
+	Model     string
+	APIKey    string
+}
+
+// Save stores a reusable profile template without changing the active
+// pointer. Credentials are written to the sibling secret store only.
+func (s Store) Save(ctx context.Context, request SaveRequest) (Profile, error) {
+	if err := requestContext(ctx); err != nil {
+		return Profile{}, err
+	}
+	if err := ValidateID(request.ID); err != nil {
+		return Profile{}, err
+	}
+	model := strings.TrimSpace(request.Model)
+	if model == "" {
+		return Profile{}, oneerrors.New(oneerrors.InvalidRequest, "model is required")
+	}
+	mode, err := configMode(request.ConfigMode)
+	if err != nil {
+		return Profile{}, err
+	}
+	base, err := provider.ProviderBase(request.Provider, request.BaseURL)
+	if err != nil {
+		return Profile{}, err
+	}
+	agents, err := normalizeAgents(request.AgentIDs)
+	if err != nil {
+		return Profile{}, err
+	}
+	existing := s.existing(request.ID)
+	if existing.ID != "" && existing.Provider != request.Provider && request.APIKey == "" {
+		return Profile{}, oneerrors.New(oneerrors.InvalidRequest, "API key is required when changing a Profile provider")
+	}
+	now := s.clock().UTC().Format(time.RFC3339)
+	label := strings.TrimSpace(request.Label)
+	if label == "" {
+		label = valueOr(existing.Label, request.ID)
+	}
+	created := existing.CreatedAt
+	if created == "" {
+		created = now
+	}
+	stored := storedProfile{
+		SchemaVersion: 2,
+		ID:            request.ID,
+		Label:         label,
+		Provider:      request.Provider,
+		BaseURL:       optionalPointer(request.BaseURL, base),
+		Model:         stringPointer(model),
+		ConfigMode:    mode,
+		AgentIDs:      agents,
+		CreatedAt:     created,
+		ActivatedAt:   existing.ActivatedAt,
+	}
+	if err := s.writeStored(ctx, stored); err != nil {
+		return Profile{}, err
+	}
+	if request.APIKey != "" && mode == "provider" {
+		if err := s.writeSecret(ctx, request.ID, request.APIKey, base); err != nil {
+			return Profile{}, err
+		}
+	}
+	profile := profileFromStored(stored)
+	profile.HasKey = s.secretExists(request.ID)
+	return profile, nil
+}
+
+// WriteActive updates the v2 profile record and active pointer used by the
+// installation workflow. It keeps the legacy v1 behavior in memory while the
+// durable migration is implemented separately.
+func (s Store) WriteActive(ctx context.Context, request ActiveRequest) (string, error) {
+	if err := requestContext(ctx); err != nil {
+		return "", err
+	}
+	agents, err := normalizeAgents(request.Agents)
+	if err != nil {
+		return "", err
+	}
+	currentResult := s.LoadActive()
+	current := Profile{}
+	if currentResult.Profile != nil {
+		current = *currentResult.Profile
+	}
+	profileID := strings.TrimSpace(request.ProfileID)
+	if profileID != "" {
+		if err := ValidateID(profileID); err != nil {
+			return "", err
+		}
+		current = s.existing(profileID)
+	} else {
+		profileID = "default"
+		if current.ID != "" {
+			profileID = current.ID
+		}
+	}
+	var baseURL *string
+	var model *string
+	resolvedBase := ""
+	providerID := "existing-account"
+	mode := "existing-account"
+	if request.Configure {
+		base, providerErr := provider.ProviderBase(request.Provider, request.BaseURL)
+		if providerErr != nil {
+			return "", providerErr
+		}
+		resolvedBase = base
+		providerID = request.Provider
+		mode = "provider"
+		baseURL = stringPointer(base)
+		modelValue := strings.TrimSpace(request.Model)
+		if modelValue == "" {
+			return "", oneerrors.New(oneerrors.InvalidRequest, "model is required")
+		}
+		model = stringPointer(modelValue)
+	}
+	if sameProfileTarget(current, providerID, mode, model) {
+		agents = mergeAgents(current.AgentIDs, agents)
+	}
+	now := s.clock().UTC().Format(time.RFC3339)
+	created := current.CreatedAt
+	if created == "" {
+		created = now
+	}
+	activated := stringPointer(now)
+	stored := storedProfile{
+		SchemaVersion: 2,
+		ID:            profileID,
+		Label:         valueOr(current.Label, profileID),
+		Provider:      providerID,
+		BaseURL:       baseURL,
+		Model:         model,
+		ConfigMode:    mode,
+		AgentIDs:      agents,
+		CreatedAt:     created,
+		ActivatedAt:   activated,
+	}
+	if err := s.writeStored(ctx, stored); err != nil {
+		return "", err
+	}
+	if request.Configure && request.APIKey != "" {
+		if err := s.writeSecret(ctx, profileID, request.APIKey, resolvedBase); err != nil {
+			return "", err
+		}
+	}
+	pointer := activePointer{SchemaVersion: 2, Active: profileID}
+	data, err := json.MarshalIndent(pointer, "", "  ")
+	if err != nil {
+		return "", writeError("Cannot encode active profile: %v", err)
+	}
+	data = append(data, '\n')
+	if _, err := s.filesystem().AtomicWrite(ctx, s.PointerPath(), data, false); err != nil {
+		return "", err
+	}
+	return s.PointerPath(), nil
+}
+
+func (s Store) ReadSecret(ctx context.Context, id string) (string, error) {
+	if err := requestContext(ctx); err != nil {
+		return "", err
+	}
+	path, err := s.SecretPath(id)
+	if err != nil {
+		return "", err
+	}
+	data, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return "", nil
+	}
+	if err != nil {
+		return "", writeError("Cannot read stored key for profile %s: %v", id, err)
+	}
+	return parseSecret(string(data), s.OS), nil
+}
+
+func (s Store) writeStored(ctx context.Context, stored storedProfile) error {
+	path, err := s.ProfilePath(stored.ID)
+	if err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(stored, "", "  ")
+	if err != nil {
+		return writeError("Cannot encode profile %s: %v", stored.ID, err)
+	}
+	data = append(data, '\n')
+	_, err = s.filesystem().AtomicWrite(ctx, path, data, false)
+	return err
+}
+
+func (s Store) writeSecret(ctx context.Context, id, apiKey, base string) error {
+	path, err := s.SecretPath(id)
+	if err != nil {
+		return err
+	}
+	content := secretContent(s.OS, apiKey, base)
+	_, err = s.filesystem().AtomicWrite(ctx, path, []byte(content), true)
+	return err
+}
+
+func (s Store) existing(id string) Profile {
+	path, err := s.ProfilePath(id)
+	if err != nil {
+		return Profile{}
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return Profile{}
+	}
+	profile, err := decodeStored(data)
+	if err != nil {
+		return Profile{}
+	}
+	return profile
+}
+
+func (s Store) secretExists(id string) bool {
+	path, err := s.SecretPath(id)
+	if err != nil {
+		return false
+	}
+	info, err := os.Stat(path)
+	return err == nil && !info.IsDir()
+}
+
+func (s Store) filesystem() securefs.Store {
+	if s.FS != nil {
+		return *s.FS
+	}
+	return securefs.New(securefs.Options{OS: s.OS})
+}
+
+func (s Store) clock() time.Time {
+	if s.Now == nil {
+		return time.Now()
+	}
+	return s.Now()
+}
+
+func profileFromStored(stored storedProfile) Profile {
+	return Profile{
+		SchemaVersion: stored.SchemaVersion,
+		ID:            stored.ID,
+		Label:         stored.Label,
+		Provider:      stored.Provider,
+		BaseURL:       stored.BaseURL,
+		Model:         stored.Model,
+		ConfigMode:    stored.ConfigMode,
+		AgentIDs:      cloneStrings(stored.AgentIDs),
+		CreatedAt:     stored.CreatedAt,
+		ActivatedAt:   stored.ActivatedAt,
+	}
+}
+
+func configMode(value string) (string, error) {
+	if value == "" {
+		return "provider", nil
+	}
+	if value != "provider" && value != "existing-account" {
+		return "", oneerrors.New(oneerrors.InvalidRequest, "config_mode must be provider or existing-account")
+	}
+	return value, nil
+}
+
+func normalizeAgents(values []string) ([]string, error) {
+	if len(values) == 0 {
+		return nil, oneerrors.New(oneerrors.InvalidRequest, "agents must be a non-empty array of Agent IDs")
+	}
+	seen := make(map[string]struct{}, len(values))
+	for _, value := range values {
+		value = strings.TrimSpace(value)
+		if value == "" {
+			return nil, oneerrors.New(oneerrors.InvalidRequest, "agents must contain non-empty Agent IDs")
+		}
+		seen[value] = struct{}{}
+	}
+	result := make([]string, 0, len(seen))
+	for value := range seen {
+		result = append(result, value)
+	}
+	sort.Strings(result)
+	return result, nil
+}
+
+func mergeAgents(first, second []string) []string {
+	values := append(append([]string{}, first...), second...)
+	result, _ := normalizeAgents(values)
+	return result
+}
+
+func sameProfileTarget(current Profile, providerID, mode string, model *string) bool {
+	if current.ID == "" || current.Provider != providerID || current.ConfigMode != mode {
+		return false
+	}
+	return optionalEqual(current.Model, model)
+}
+
+func optionalEqual(first, second *string) bool {
+	if first == nil || second == nil {
+		return first == nil && second == nil
+	}
+	return *first == *second
+}
+
+func optionalPointer(input, resolved string) *string {
+	if input == "" {
+		return nil
+	}
+	return stringPointer(resolved)
+}
+
+func secretContent(osID, apiKey, base string) string {
+	if osID == "windows" {
+		return "$env:ONEAGENT_API_KEY = '" + powershellQuote(apiKey) + "'\n" +
+			"$env:ONEAGENT_API_BASE_URL = '" + powershellQuote(base) + "'\n"
+	}
+	return "export ONEAGENT_API_KEY=" + shellQuote(apiKey) + "\n" +
+		"export ONEAGENT_API_BASE_URL=" + shellQuote(base) + "\n"
+}
+
+func shellQuote(value string) string {
+	if value != "" {
+		safe := true
+		for _, character := range value {
+			if !strings.ContainsRune("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_@%+=:,./-", character) {
+				safe = false
+				break
+			}
+		}
+		if safe {
+			return value
+		}
+	}
+	return "'" + strings.ReplaceAll(value, "'", "'\\''") + "'"
+}
+
+func powershellQuote(value string) string {
+	return strings.ReplaceAll(value, "'", "''")
+}
+
+func parseSecret(content, osID string) string {
+	prefix := "export ONEAGENT_API_KEY="
+	if osID == "windows" {
+		prefix = "$env:ONEAGENT_API_KEY = "
+	}
+	for line := range strings.SplitSeq(content, "\n") {
+		line = strings.TrimSpace(line)
+		if !strings.HasPrefix(line, prefix) {
+			continue
+		}
+		value := strings.TrimSpace(strings.TrimPrefix(line, prefix))
+		if osID == "windows" && len(value) >= 2 && value[0] == '\'' && value[len(value)-1] == '\'' {
+			return strings.ReplaceAll(value[1:len(value)-1], "''", "'")
+		}
+		if strings.HasPrefix(value, "'") && strings.HasSuffix(value, "'") {
+			return strings.ReplaceAll(value[1:len(value)-1], "'\\''", "'")
+		}
+		return value
+	}
+	return ""
+}
+
+func requestContext(ctx context.Context) error {
+	if ctx == nil {
+		return nil
+	}
+	if err := ctx.Err(); err != nil {
+		return oneerrors.New(oneerrors.Timeout, "Profile request was cancelled", oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+	}
+	return nil
+}
+
+func writeError(format string, values ...any) error {
+	return oneerrors.New(oneerrors.ConfigWriteFailed, fmt.Sprintf(format, values...))
+}
diff --git a/internal/profile/write_test.go b/internal/profile/write_test.go
new file mode 100644
index 00000000..a41ecfbf
--- /dev/null
+++ b/internal/profile/write_test.go
@@ -0,0 +1,203 @@
+package profile
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+func testStore(t *testing.T, home, osID string) Store {
+	t.Helper()
+	filesystem := securefs.New(securefs.Options{OS: osID, Now: fixedProfileClock})
+	return NewStoreWithDependencies(home, osID, filesystem, fixedProfileClock)
+}
+
+func fixedProfileClock() time.Time {
+	return time.Date(2026, time.July, 30, 13, 14, 15, 0, time.UTC)
+}
+
+func TestSaveProfileIsolatesSecretAndPreservesHistory(t *testing.T) {
+	home := t.TempDir()
+	store := testStore(t, home, "linux")
+	secret := "sk-quoted'value"
+	profile, err := store.Save(context.Background(), SaveRequest{
+		ID:       "ppio-deepseek",
+		Label:    "Team PPIO",
+		Provider: "ppio",
+		Model:    "deepseek-v3",
+		AgentIDs: []string{"opencode", "codex", "codex"},
+		APIKey:   secret,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if profile.ID != "ppio-deepseek" || !profile.HasKey || !reflect.DeepEqual(profile.AgentIDs, []string{"codex", "opencode"}) {
+		t.Fatalf("saved profile = %#v", profile)
+	}
+	profilePath, _ := store.ProfilePath("ppio-deepseek")
+	profileData, err := os.ReadFile(profilePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(profileData), secret) || strings.Contains(string(profileData), "api_key") {
+		t.Fatalf("profile file leaked secret material: %s", profileData)
+	}
+	secretPath, _ := store.SecretPath("ppio-deepseek")
+	secretData, err := os.ReadFile(secretPath)
+	if err != nil || !strings.Contains(string(secretData), "ONEAGENT_API_KEY") {
+		t.Fatalf("secret file = %q, err=%v", secretData, err)
+	}
+	if got, err := store.ReadSecret(context.Background(), "ppio-deepseek"); err != nil || got != secret {
+		t.Fatalf("ReadSecret() = %q, %v", got, err)
+	}
+	if got := store.List(); len(got) != 1 || !got[0].HasKey {
+		t.Fatalf("List() = %#v", got)
+	}
+	created := profile.CreatedAt
+	updated, err := store.Save(context.Background(), SaveRequest{
+		ID:       "ppio-deepseek",
+		Provider: "ppio",
+		Model:    "model-b",
+		AgentIDs: []string{"codex"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if updated.Label != "Team PPIO" || updated.CreatedAt != created || updated.Model == nil || *updated.Model != "model-b" || !updated.HasKey {
+		t.Fatalf("updated profile = %#v", updated)
+	}
+	if _, err := store.Save(context.Background(), SaveRequest{
+		ID: "ppio-deepseek", Provider: "novita", Model: "model-b", AgentIDs: []string{"codex"},
+	}); err == nil || oneerrors.As(err).Code != oneerrors.InvalidRequest {
+		t.Fatalf("provider change without a new key returned %v", err)
+	}
+	assertProfileMode(t, profilePath, 0o600)
+	assertProfileMode(t, secretPath, 0o600)
+}
+
+func TestSaveProfileValidatesInputAndCustomBase(t *testing.T) {
+	store := testStore(t, t.TempDir(), "linux")
+	for _, request := range []SaveRequest{
+		{ID: "../bad", Provider: "ppio", Model: "m", AgentIDs: []string{"codex"}},
+		{ID: "ok", Provider: "nope", Model: "m", AgentIDs: []string{"codex"}},
+		{ID: "ok", Provider: "ppio", Model: "", AgentIDs: []string{"codex"}},
+		{ID: "ok", Provider: "ppio", Model: "m", AgentIDs: nil},
+	} {
+		if _, err := store.Save(context.Background(), request); err == nil || oneerrors.As(err).Code != oneerrors.InvalidRequest {
+			t.Errorf("invalid request %#v returned %v", request, err)
+		}
+	}
+	profile, err := store.Save(context.Background(), SaveRequest{
+		ID:       "custom-local",
+		Provider: "custom",
+		BaseURL:  "http://127.0.0.1:9000/",
+		Model:    "m",
+		AgentIDs: []string{"codex"},
+	})
+	if err != nil || profile.BaseURL == nil || *profile.BaseURL != "http://127.0.0.1:9000" {
+		t.Fatalf("custom profile = %#v, err=%v", profile, err)
+	}
+}
+
+func TestWriteActiveMergesAgentsAndSupportsExistingAccount(t *testing.T) {
+	store := testStore(t, t.TempDir(), "linux")
+	if _, err := store.WriteActive(context.Background(), ActiveRequest{
+		Agents: []string{"codex"}, Configure: true, Provider: "ppio", Model: "model-a", APIKey: "sk-a",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := store.WriteActive(context.Background(), ActiveRequest{
+		Agents: []string{"opencode"}, Configure: true, Provider: "ppio", Model: "model-a",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	active := store.LoadActive()
+	if active.Error != "" || active.Profile == nil || !reflect.DeepEqual(active.Profile.AgentIDs, []string{"codex", "opencode"}) {
+		t.Fatalf("merged active profile = %#v", active)
+	}
+	if active.Profile.BaseURL == nil || *active.Profile.BaseURL != "https://api.ppio.com/openai" {
+		t.Fatalf("active base URL = %#v", active.Profile.BaseURL)
+	}
+	if got, err := store.ReadSecret(context.Background(), "default"); err != nil || got != "sk-a" {
+		t.Fatalf("preserved active secret = %q, %v", got, err)
+	}
+	if _, err := store.WriteActive(context.Background(), ActiveRequest{
+		Agents: []string{"aider"}, Configure: true, Provider: "novita", Model: "model-b",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	active = store.LoadActive()
+	if active.Profile.Provider != "novita" || !reflect.DeepEqual(active.Profile.AgentIDs, []string{"aider"}) {
+		t.Fatalf("replaced active profile = %#v", active.Profile)
+	}
+	if _, err := store.WriteActive(context.Background(), ActiveRequest{Agents: []string{"codex"}, Configure: false}); err != nil {
+		t.Fatal(err)
+	}
+	active = store.LoadActive()
+	if active.Profile.ConfigMode != "existing-account" || active.Profile.Provider != "existing-account" || active.Profile.Model != nil || active.Profile.BaseURL != nil {
+		t.Fatalf("existing account profile = %#v", active.Profile)
+	}
+	var pointer map[string]any
+	data, _ := os.ReadFile(store.PointerPath())
+	if err := json.Unmarshal(data, &pointer); err != nil || pointer["active"] != "default" || pointer["schema_version"] != float64(2) {
+		t.Fatalf("active pointer = %s, %v", data, err)
+	}
+	if got := string(data); !strings.HasPrefix(got, "{\n  \"schema_version\": 2,\n  \"active\": \"default\"\n}") {
+		t.Fatalf("active pointer key order changed: %s", data)
+	}
+}
+
+func TestProfileWritesHonorCancellation(t *testing.T) {
+	store := testStore(t, t.TempDir(), "linux")
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err := store.Save(ctx, SaveRequest{ID: "team", Provider: "ppio", Model: "m", AgentIDs: []string{"codex"}})
+	if err == nil || oneerrors.As(err).Code != oneerrors.Timeout {
+		t.Fatalf("cancelled Save() = %v", err)
+	}
+	if _, err := store.ReadSecret(ctx, "team"); err == nil || oneerrors.As(err).Code != oneerrors.Timeout {
+		t.Fatalf("cancelled ReadSecret() = %v", err)
+	}
+}
+
+func TestWindowsSecretUsesPowerShellQuoting(t *testing.T) {
+	store := testStore(t, t.TempDir(), "windows")
+	// Replace the default securefs command runner with a no-op runner while
+	// preserving the Windows ACL argument construction.
+	filesystem := securefs.New(securefs.Options{
+		OS:       "windows",
+		Username: "tester",
+		Run:      func(context.Context, []string) error { return nil },
+		Now:      fixedProfileClock,
+	})
+	store = NewStoreWithDependencies(store.Home, "windows", filesystem, fixedProfileClock)
+	if _, err := store.Save(context.Background(), SaveRequest{ID: "win", Provider: "ppio", Model: "m", AgentIDs: []string{"codex"}, APIKey: "key'value"}); err != nil {
+		t.Fatal(err)
+	}
+	path, _ := store.SecretPath("win")
+	data, _ := os.ReadFile(path)
+	if !strings.Contains(string(data), "$env:ONEAGENT_API_KEY = 'key''value'") {
+		t.Fatalf("PowerShell secret = %q", data)
+	}
+	if got, err := store.ReadSecret(context.Background(), "win"); err != nil || got != "key'value" {
+		t.Fatalf("Windows ReadSecret() = %q, %v", got, err)
+	}
+}
+
+func assertProfileMode(t *testing.T, path string, want os.FileMode) {
+	t.Helper()
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := info.Mode().Perm(); got != want {
+		t.Fatalf("%s mode = %o, want %o", path, got, want)
+	}
+}
diff --git a/internal/provider/client.go b/internal/provider/client.go
new file mode 100644
index 00000000..82a3fe96
--- /dev/null
+++ b/internal/provider/client.go
@@ -0,0 +1,423 @@
+package provider
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"strings"
+	"time"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+)
+
+const (
+	defaultTimeout    = 10 * time.Second
+	defaultMaxBody    = 1 << 20
+	unsupportedStatus = 0
+)
+
+// HTTPDoer is deliberately smaller than *http.Client so tests and callers can
+// provide a transport without opening a real network connection.
+type HTTPDoer interface {
+	Do(*http.Request) (*http.Response, error)
+}
+
+type Client struct {
+	doer    HTTPDoer
+	timeout time.Duration
+	maxBody int64
+}
+
+func NewClient(doer HTTPDoer) *Client {
+	if doer == nil {
+		doer = &http.Client{}
+	}
+	return &Client{doer: doer, timeout: defaultTimeout, maxBody: defaultMaxBody}
+}
+
+// NewClientWithLimits is useful for integration tests and keeps operational
+// limits explicit at the one place where requests are created.
+func NewClientWithLimits(doer HTTPDoer, timeout time.Duration, maxBody int64) *Client {
+	client := NewClient(doer)
+	if timeout > 0 {
+		client.timeout = timeout
+	}
+	if maxBody > 0 {
+		client.maxBody = maxBody
+	}
+	return client
+}
+
+type ProbeResult struct {
+	OK        bool    `json:"ok"`
+	Reachable bool    `json:"reachable"`
+	Status    int     `json:"status"`
+	Message   string  `json:"message"`
+	ErrorCode *string `json:"error_code"`
+	Retryable bool    `json:"retryable"`
+	Protocol  *string `json:"protocol"`
+}
+
+type ModelsResult struct {
+	OK        bool     `json:"ok"`
+	Reachable bool     `json:"reachable"`
+	Status    int      `json:"status"`
+	Message   string   `json:"message"`
+	ErrorCode *string  `json:"error_code"`
+	Retryable bool     `json:"retryable"`
+	Protocol  *string  `json:"protocol"`
+	Models    []string `json:"models"`
+}
+
+func (c *Client) Probe(ctx context.Context, protocol, providerID, apiKey, model, customBase string) (ProbeResult, error) {
+	if apiKey == "" {
+		return ProbeResult{}, oneerrors.New(oneerrors.InvalidRequest, "API key is required")
+	}
+	if protocol != ProtocolOpenAI && protocol != ProtocolAnthropic && protocol != ProtocolResponses {
+		return ProbeResult{}, invalidProtocol(protocol)
+	}
+	requestModel := model
+	if requestModel == "" {
+		requestModel = FallbackProbeModel(providerID)
+	}
+	request, err := protocolRequest(ctx, protocol, providerID, customBase, apiKey, requestModel)
+	if err != nil {
+		return ProbeResult{}, err
+	}
+	response, cancelRequest, err := c.do(request)
+	defer cancelRequest()
+	if err != nil {
+		if response != nil && response.Body != nil {
+			_ = response.Body.Close()
+		}
+		result := transportResult(err)
+		result.Protocol = new(protocol)
+		return result, nil
+	}
+	if response == nil {
+		result := transportResult(errors.New("Provider transport returned no response"))
+		result.Protocol = new(protocol)
+		return result, nil
+	}
+	defer response.Body.Close()
+	if response.StatusCode >= 200 && response.StatusCode < 300 {
+		// Keep the connection reusable without allowing a successful endpoint to
+		// stream an unbounded response into the process.
+		_, _ = io.Copy(io.Discard, io.LimitReader(response.Body, c.maxBody))
+		return ProbeResult{
+			OK:        response.StatusCode == http.StatusOK || response.StatusCode == http.StatusNoContent,
+			Reachable: true,
+			Status:    response.StatusCode,
+			Message:   fmt.Sprintf("%s connection test passed.", ProtocolLabel(protocol)),
+			Retryable: false,
+			Protocol:  new(protocol),
+		}, nil
+	}
+	body, _, _ := c.readBody(response.Body)
+	return classifyHTTPProbe(response.StatusCode, string(body), protocol, requestModel), nil
+}
+
+func (c *Client) ListModels(ctx context.Context, providerID, apiKey, customBase string) (ModelsResult, error) {
+	if apiKey == "" {
+		return ModelsResult{}, oneerrors.New(oneerrors.InvalidRequest, "API key is required")
+	}
+	base, err := ProviderBase(providerID, customBase)
+	if err != nil {
+		return ModelsResult{}, err
+	}
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, OpenAIBaseURL(base)+"/models", nil)
+	if err != nil {
+		return ModelsResult{}, oneerrors.New(oneerrors.InvalidRequest, "Provider endpoint is invalid", oneerrors.WithCause(err))
+	}
+	request.Header.Set("Authorization", "Bearer "+apiKey)
+	response, cancelRequest, err := c.do(request)
+	defer cancelRequest()
+	if err != nil {
+		if response != nil && response.Body != nil {
+			_ = response.Body.Close()
+		}
+		result := transportModelsResult(err)
+		return result, nil
+	}
+	if response == nil {
+		return transportModelsResult(errors.New("Provider transport returned no response")), nil
+	}
+	defer response.Body.Close()
+	if response.StatusCode < 200 || response.StatusCode >= 300 {
+		return classifyHTTPModels(response.StatusCode), nil
+	}
+	body, tooLarge, readErr := c.readBody(response.Body)
+	if readErr != nil {
+		return transportModelsResult(readErr), nil
+	}
+	if tooLarge {
+		return modelsFailure("Model list response is too large; enter model ID manually."), nil
+	}
+	var raw any
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return ModelsResult{
+			Reachable: true,
+			Status:    response.StatusCode,
+			Message:   fmt.Sprintf("Model list response is not valid JSON: %v", err),
+			ErrorCode: new(oneerrors.ModelsUnsupported),
+			Models:    []string{},
+		}, nil
+	}
+	models := modelIDs(raw)
+	result := ModelsResult{Reachable: true, Status: response.StatusCode, Models: models}
+	if len(models) > 0 {
+		result.OK = true
+		result.Message = fmt.Sprintf("Found %d models.", len(models))
+	} else {
+		result.Message = "No model IDs returned; enter model ID manually."
+		result.ErrorCode = new(oneerrors.ModelsUnsupported)
+	}
+	return result, nil
+}
+
+// ResolveProbeModel prefers a live chat-capable ID but keeps discovery failure
+// non-fatal so callers can still use the provider fallback model.
+func (c *Client) ResolveProbeModel(ctx context.Context, providerID, apiKey, model, customBase string) (string, error) {
+	if model != "" || apiKey == "" {
+		if model != "" {
+			return model, nil
+		}
+		return FallbackProbeModel(providerID), nil
+	}
+	listing, err := c.ListModels(ctx, providerID, apiKey, customBase)
+	if err != nil {
+		return "", err
+	}
+	if listing.OK && len(listing.Models) > 0 {
+		return PickChatModel(listing.Models), nil
+	}
+	return FallbackProbeModel(providerID), nil
+}
+
+func protocolRequest(ctx context.Context, protocol, providerID, customBase, apiKey, model string) (*http.Request, error) {
+	var (
+		endpoint string
+		body     any
+	)
+	headers := map[string]string{
+		"Authorization": "Bearer " + apiKey,
+		"Content-Type":  "application/json",
+	}
+	if protocol == ProtocolAnthropic {
+		base, err := ProviderConfigBase(providerID, customBase, protocol)
+		if err != nil {
+			return nil, err
+		}
+		endpoint = AnthropicMessagesURL(base)
+		headers["X-Api-Key"] = apiKey
+		headers["Anthropic-Version"] = "2023-06-01"
+		body = map[string]any{
+			"model":      model,
+			"messages":   []map[string]string{{"role": "user", "content": "ping"}},
+			"max_tokens": 1,
+		}
+	} else {
+		base, err := ProviderBase(providerID, customBase)
+		if err != nil {
+			return nil, err
+		}
+		v1 := OpenAIBaseURL(base)
+		if protocol == ProtocolResponses {
+			endpoint = v1 + "/responses"
+			body = map[string]any{"model": model, "input": "ping", "max_output_tokens": 16}
+		} else {
+			endpoint = v1 + "/chat/completions"
+			body = map[string]any{
+				"model":      model,
+				"messages":   []map[string]string{{"role": "user", "content": "ping"}},
+				"max_tokens": 1,
+			}
+		}
+	}
+	payload, err := json.Marshal(body)
+	if err != nil {
+		return nil, oneerrors.New(oneerrors.InternalError, "Unable to build Provider request", oneerrors.WithCause(err))
+	}
+	request, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(payload))
+	if err != nil {
+		return nil, oneerrors.New(oneerrors.InvalidRequest, "Provider endpoint is invalid", oneerrors.WithCause(err))
+	}
+	for key, value := range headers {
+		request.Header.Set(key, value)
+	}
+	return request, nil
+}
+
+func (c *Client) do(request *http.Request) (*http.Response, context.CancelFunc, error) {
+	timeout := c.timeout
+	if timeout <= 0 {
+		timeout = defaultTimeout
+	}
+	ctx, cancel := context.WithTimeout(request.Context(), timeout)
+	response, err := c.doer.Do(request.WithContext(ctx))
+	return response, cancel, err
+}
+
+func (c *Client) readBody(reader io.Reader) ([]byte, bool, error) {
+	limit := c.maxBody
+	if limit <= 0 {
+		limit = defaultMaxBody
+	}
+	data, err := io.ReadAll(io.LimitReader(reader, limit+1))
+	if err != nil {
+		return nil, false, err
+	}
+	if int64(len(data)) > limit {
+		return data[:limit], true, nil
+	}
+	return data, false, nil
+}
+
+func classifyHTTPProbe(status int, body, protocol, model string) ProbeResult {
+	label := ProtocolLabel(protocol)
+	if unsupportedProtocol(status, body) {
+		return ProbeResult{
+			Reachable: true,
+			Status:    status,
+			Message:   fmt.Sprintf("Model %q does not support %s. Choose a model that serves this protocol.", model, label),
+			ErrorCode: new(oneerrors.ProtocolUnsupported),
+			Protocol:  new(protocol),
+		}
+	}
+	if status == http.StatusUnauthorized || status == http.StatusForbidden {
+		return ProbeResult{
+			Reachable: true,
+			Status:    status,
+			Message:   fmt.Sprintf("API key was rejected (%d).", status),
+			ErrorCode: new(oneerrors.APIKeyRejected),
+			Retryable: true,
+			Protocol:  new(protocol),
+		}
+	}
+	return ProbeResult{
+		Reachable: true,
+		Status:    status,
+		Message:   fmt.Sprintf("Endpoint returned HTTP %d.", status),
+		ErrorCode: new(oneerrors.ProviderUnreachable),
+		Retryable: status >= 500,
+		Protocol:  new(protocol),
+	}
+}
+
+func classifyHTTPModels(status int) ModelsResult {
+	if status == http.StatusUnauthorized || status == http.StatusForbidden {
+		return ModelsResult{
+			Reachable: true,
+			Status:    status,
+			Message:   fmt.Sprintf("API key was rejected (%d). Enter model ID manually.", status),
+			ErrorCode: new(oneerrors.APIKeyRejected),
+			Retryable: true,
+			Models:    []string{},
+		}
+	}
+	if status == http.StatusNotFound || status == http.StatusMethodNotAllowed {
+		return ModelsResult{
+			Reachable: true,
+			Status:    status,
+			Message:   fmt.Sprintf("This endpoint does not expose /v1/models (%d); enter model ID manually.", status),
+			ErrorCode: new(oneerrors.ModelsUnsupported),
+			Models:    []string{},
+		}
+	}
+	return ModelsResult{
+		Reachable: true,
+		Status:    status,
+		Message:   fmt.Sprintf("Endpoint returned HTTP %d.", status),
+		ErrorCode: new(oneerrors.ProviderUnreachable),
+		Retryable: status >= 500,
+		Models:    []string{},
+	}
+}
+
+func transportResult(err error) ProbeResult {
+	code, retryable := transportCode(err)
+	return ProbeResult{
+		Status:    unsupportedStatus,
+		Message:   fmt.Sprintf("Cannot reach endpoint: %s", err),
+		ErrorCode: new(code),
+		Retryable: retryable,
+	}
+}
+
+func transportModelsResult(err error) ModelsResult {
+	code, retryable := transportCode(err)
+	return ModelsResult{
+		Status:    unsupportedStatus,
+		Message:   fmt.Sprintf("Cannot reach endpoint: %s", err),
+		ErrorCode: new(code),
+		Retryable: retryable,
+		Models:    []string{},
+	}
+}
+
+func transportCode(err error) (string, bool) {
+	if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
+		return oneerrors.Timeout, true
+	}
+	var networkError net.Error
+	if errors.As(err, &networkError) && networkError.Timeout() {
+		return oneerrors.Timeout, true
+	}
+	if strings.Contains(strings.ToLower(err.Error()), "timed out") {
+		return oneerrors.Timeout, true
+	}
+	return oneerrors.ProviderUnreachable, true
+}
+
+func modelsFailure(message string) ModelsResult {
+	return ModelsResult{
+		Reachable: true,
+		Status:    http.StatusOK,
+		Message:   message,
+		ErrorCode: new(oneerrors.ModelsUnsupported),
+		Models:    []string{},
+	}
+}
+
+func modelIDs(raw any) []string {
+	data := raw
+	if object, ok := raw.(map[string]any); ok {
+		data = object["data"]
+	}
+	items, ok := data.([]any)
+	if !ok {
+		return []string{}
+	}
+	models := make([]string, 0, len(items))
+	for _, item := range items {
+		switch value := item.(type) {
+		case string:
+			models = append(models, value)
+		case map[string]any:
+			if id, ok := value["id"]; ok && id != nil {
+				models = append(models, fmt.Sprint(id))
+			}
+		}
+	}
+	return models
+}
+
+func unsupportedProtocol(status int, body string) bool {
+	if status == http.StatusNotFound || status == http.StatusMethodNotAllowed || status == http.StatusNotImplemented {
+		return true
+	}
+	if status == http.StatusBadRequest || status == http.StatusUnprocessableEntity || status == http.StatusInternalServerError {
+		lowered := strings.ToLower(body)
+		for _, marker := range []string{"does not support endpoint", "not implemented", "unsupported endpoint", "unknown endpoint"} {
+			if strings.Contains(lowered, marker) {
+				return true
+			}
+		}
+	}
+	return false
+}
diff --git a/internal/provider/client_test.go b/internal/provider/client_test.go
new file mode 100644
index 00000000..0cd11ce3
--- /dev/null
+++ b/internal/provider/client_test.go
@@ -0,0 +1,256 @@
+package provider
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/url"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+)
+
+type fakeDoer func(*http.Request) (*http.Response, error)
+
+func (fake fakeDoer) Do(request *http.Request) (*http.Response, error) {
+	return fake(request)
+}
+
+func fakeResponse(status int, body string) *http.Response {
+	return &http.Response{
+		StatusCode: status,
+		Body:       io.NopCloser(strings.NewReader(body)),
+		Header:     make(http.Header),
+	}
+}
+
+type contextAwareBody struct {
+	ctx  context.Context
+	data *strings.Reader
+}
+
+func (body *contextAwareBody) Read(target []byte) (int, error) {
+	if err := body.ctx.Err(); err != nil {
+		return 0, err
+	}
+	return body.data.Read(target)
+}
+
+func (body *contextAwareBody) Close() error { return nil }
+
+func TestProbeBuildsProtocolSpecificRequests(t *testing.T) {
+	tests := []struct {
+		protocol string
+		path     string
+		bodyKey  string
+	}{
+		{ProtocolOpenAI, "/v1/chat/completions", "messages"},
+		{ProtocolResponses, "/v1/responses", "input"},
+		{ProtocolAnthropic, "/v1/messages", "messages"},
+	}
+	for _, test := range tests {
+		t.Run(test.protocol, func(t *testing.T) {
+			var seen *http.Request
+			client := NewClient(fakeDoer(func(request *http.Request) (*http.Response, error) {
+				seen = request
+				return fakeResponse(http.StatusOK, `{}`), nil
+			}))
+			result, err := client.Probe(context.Background(), test.protocol, "custom", "key", "model-a", "https://proxy.test/v1")
+			if err != nil {
+				t.Fatal(err)
+			}
+			if !result.OK || result.Protocol == nil || *result.Protocol != test.protocol {
+				t.Fatalf("probe result = %#v", result)
+			}
+			if seen == nil || seen.URL.Path != test.path {
+				t.Fatalf("request path = %v, want %s", seen.URL, test.path)
+			}
+			var body map[string]any
+			if err := json.NewDecoder(seen.Body).Decode(&body); err != nil {
+				t.Fatal(err)
+			}
+			if _, ok := body[test.bodyKey]; !ok {
+				t.Fatalf("request body %#v does not contain %q", body, test.bodyKey)
+			}
+			if seen.Header.Get("Authorization") != "Bearer key" {
+				t.Fatal("Authorization header was not set")
+			}
+			if test.protocol == ProtocolAnthropic {
+				if seen.Header.Get("X-Api-Key") != "key" || seen.Header.Get("Anthropic-Version") != "2023-06-01" {
+					t.Fatal("Anthropic headers were not set")
+				}
+			} else if seen.Header.Get("X-Api-Key") != "" {
+				t.Fatal("OpenAI request unexpectedly sent X-Api-Key")
+			}
+		})
+	}
+}
+
+func TestProbeClassifiesUnsupportedAndTransientResponses(t *testing.T) {
+	unsupported := NewClient(fakeDoer(func(*http.Request) (*http.Response, error) {
+		return fakeResponse(http.StatusBadRequest, `{"message":"model does not support endpoint"}`), nil
+	}))
+	result, err := unsupported.Probe(context.Background(), ProtocolResponses, "custom", "key", "model-a", "https://proxy.test/v1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.ErrorCode == nil || *result.ErrorCode != oneerrors.ProtocolUnsupported || result.Retryable || result.Reachable != true {
+		t.Fatalf("unsupported result = %#v", result)
+	}
+
+	transient := NewClient(fakeDoer(func(*http.Request) (*http.Response, error) {
+		return fakeResponse(http.StatusServiceUnavailable, `{"error":"busy"}`), nil
+	}))
+	result, err = transient.Probe(context.Background(), ProtocolResponses, "custom", "key", "model-a", "https://proxy.test/v1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.ErrorCode == nil || *result.ErrorCode == oneerrors.ProtocolUnsupported || !result.Retryable || result.Protocol == nil {
+		t.Fatalf("transient result = %#v", result)
+	}
+}
+
+func TestProbeTransportAndInputErrors(t *testing.T) {
+	client := NewClient(fakeDoer(func(*http.Request) (*http.Response, error) {
+		return nil, errors.New("connection refused")
+	}))
+	result, err := client.Probe(context.Background(), ProtocolOpenAI, "ppio", "key", "model", "")
+	if err != nil || result.ErrorCode == nil || *result.ErrorCode != oneerrors.ProviderUnreachable || result.Reachable || !result.Retryable {
+		t.Fatalf("transport result = %#v, err=%v", result, err)
+	}
+	if _, err := client.Probe(context.Background(), ProtocolOpenAI, "ppio", "", "model", ""); err == nil || oneerrors.As(err).Code != oneerrors.InvalidRequest {
+		t.Fatalf("missing key error = %v", err)
+	}
+	if _, err := client.Probe(context.Background(), "grpc", "ppio", "key", "model", ""); err == nil || oneerrors.As(err).Code != oneerrors.InvalidRequest {
+		t.Fatalf("unknown protocol error = %v", err)
+	}
+}
+
+func TestListModelsShapesAndErrors(t *testing.T) {
+	responses := []string{
+		`["model-a", {"id":"model-b"}, {"ignored":true}]`,
+		`{"data":[{"id":"model-c"}]}`,
+	}
+	for _, body := range responses {
+		client := NewClient(fakeDoer(func(*http.Request) (*http.Response, error) {
+			return fakeResponse(http.StatusOK, body), nil
+		}))
+		result, err := client.ListModels(context.Background(), "ppio", "key", "")
+		if err != nil || !result.OK || !reflect.DeepEqual(result.Models, func() []string {
+			if strings.Contains(body, "model-c") {
+				return []string{"model-c"}
+			}
+			return []string{"model-a", "model-b"}
+		}()) {
+			t.Fatalf("ListModels(%s) = %#v, err=%v", body, result, err)
+		}
+	}
+	invalid := NewClient(fakeDoer(func(*http.Request) (*http.Response, error) {
+		return fakeResponse(http.StatusOK, "not-json"), nil
+	}))
+	result, err := invalid.ListModels(context.Background(), "ppio", "key", "")
+	if err != nil || result.ErrorCode == nil || *result.ErrorCode != oneerrors.ModelsUnsupported || len(result.Models) != 0 {
+		t.Fatalf("invalid JSON result = %#v, err=%v", result, err)
+	}
+	missing := NewClient(fakeDoer(func(request *http.Request) (*http.Response, error) {
+		if request.URL.Path != "/openai/v1/models" {
+			t.Errorf("model URL path = %s", request.URL.Path)
+		}
+		return fakeResponse(http.StatusNotFound, ""), nil
+	}))
+	result, err = missing.ListModels(context.Background(), "ppio", "key", "")
+	if err != nil || result.ErrorCode == nil || *result.ErrorCode != oneerrors.ModelsUnsupported || result.Retryable || len(result.Models) != 0 {
+		t.Fatalf("missing model endpoint result = %#v, err=%v", result, err)
+	}
+}
+
+func TestListModelsTransportTimeoutAndSizeLimit(t *testing.T) {
+	timeoutClient := NewClient(fakeDoer(func(request *http.Request) (*http.Response, error) {
+		return nil, &url.Error{Op: "Get", URL: request.URL.String(), Err: context.DeadlineExceeded}
+	}))
+	result, err := timeoutClient.ListModels(context.Background(), "ppio", "key", "")
+	if err != nil || result.ErrorCode == nil || *result.ErrorCode != oneerrors.Timeout {
+		t.Fatalf("timeout result = %#v, err=%v", result, err)
+	}
+	large := NewClientWithLimits(fakeDoer(func(*http.Request) (*http.Response, error) {
+		return fakeResponse(http.StatusOK, strings.Repeat("x", 32)), nil
+	}), time.Second, 8)
+	result, err = large.ListModels(context.Background(), "ppio", "key", "")
+	if err != nil || result.ErrorCode == nil || *result.ErrorCode != oneerrors.ModelsUnsupported {
+		t.Fatalf("large response result = %#v, err=%v", result, err)
+	}
+}
+
+func TestClientKeepsRequestContextAliveWhileReadingBody(t *testing.T) {
+	client := NewClient(fakeDoer(func(request *http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Body: &contextAwareBody{
+				ctx:  request.Context(),
+				data: strings.NewReader(`{"data":[{"id":"chat-model"}]}`),
+			},
+			Header: make(http.Header),
+		}, nil
+	}))
+	result, err := client.ListModels(context.Background(), "ppio", "key", "")
+	if err != nil || !result.OK || !reflect.DeepEqual(result.Models, []string{"chat-model"}) {
+		t.Fatalf("context-aware body result = %#v, err=%v", result, err)
+	}
+}
+
+func TestResolveProbeModelUsesDiscoveryOnlyWhenNeeded(t *testing.T) {
+	called := false
+	client := NewClient(fakeDoer(func(*http.Request) (*http.Response, error) {
+		called = true
+		return fakeResponse(http.StatusOK, `{"data":[{"id":"text-embedding-3-small"},{"id":"chat-model"} ]}`), nil
+	}))
+	model, err := client.ResolveProbeModel(context.Background(), "ppio", "key", "", "")
+	if err != nil || model != "chat-model" || !called {
+		t.Fatalf("discovered model = %q, err=%v, called=%v", model, err, called)
+	}
+	called = false
+	model, err = client.ResolveProbeModel(context.Background(), "ppio", "", "", "")
+	if err != nil || model != FallbackProbeModel("ppio") || called {
+		t.Fatalf("fallback model = %q, err=%v, called=%v", model, err, called)
+	}
+	model, err = client.ResolveProbeModel(context.Background(), "ppio", "key", "chosen", "")
+	if err != nil || model != "chosen" || called {
+		t.Fatalf("chosen model = %q, err=%v, called=%v", model, err, called)
+	}
+}
+
+func TestClientPropagatesContextCancellation(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	client := NewClient(fakeDoer(func(request *http.Request) (*http.Response, error) {
+		return nil, request.Context().Err()
+	}))
+	result, err := client.ListModels(ctx, "ppio", "key", "")
+	if err != nil || result.ErrorCode == nil || *result.ErrorCode != oneerrors.Timeout {
+		t.Fatalf("cancelled result = %#v, err=%v", result, err)
+	}
+}
+
+type failingBody struct{ err error }
+
+func (body failingBody) Read([]byte) (int, error) { return 0, body.err }
+func (failingBody) Close() error                  { return nil }
+
+func TestListModelsMapsBodyReadCancellationToTimeout(t *testing.T) {
+	client := NewClient(fakeDoer(func(*http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Body:       failingBody{err: context.Canceled},
+			Header:     make(http.Header),
+		}, nil
+	}))
+	result, err := client.ListModels(context.Background(), "ppio", "key", "")
+	if err != nil || result.ErrorCode == nil || *result.ErrorCode != oneerrors.Timeout || result.Reachable {
+		t.Fatalf("body cancellation result = %#v, err=%v", result, err)
+	}
+}
diff --git a/internal/provider/provider.go b/internal/provider/provider.go
new file mode 100644
index 00000000..d4c1c082
--- /dev/null
+++ b/internal/provider/provider.go
@@ -0,0 +1,151 @@
+// Package provider contains transport-independent Provider and protocol
+// rules. Network clients are kept separate so these checks can be reused by
+// the CLI and Wails bindings without opening a request during validation.
+package provider
+
+import (
+	"fmt"
+	"net/url"
+	"regexp"
+	"strings"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+)
+
+const (
+	ProtocolOpenAI    = catalog.ProtocolOpenAI
+	ProtocolAnthropic = catalog.ProtocolAnthropic
+	ProtocolResponses = catalog.ProtocolResponses
+)
+
+var nonChatModel = regexp.MustCompile(`(?i)(^|[-_/.])(embed(ding)?s?|rerank(er)?s?|ocr|whisper|asr|tts|speech|vl|vision|image|sdx?|flux|guard(rail)?s?|moderation|sql)([-_/.]|$)`)
+
+// ValidateBaseURL accepts an explicit HTTP(S) origin or path and rejects the
+// forms that could smuggle credentials or control characters into requests.
+func ValidateBaseURL(value string) (string, error) {
+	if value == "" {
+		return "", oneerrors.New(oneerrors.InvalidRequest, "Custom base URL is required")
+	}
+	for _, character := range value {
+		if character < 32 || character == 127 {
+			return "", oneerrors.New(oneerrors.InvalidRequest, "Custom base URL contains control characters")
+		}
+	}
+	parsed, err := url.Parse(value)
+	if err != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.Host == "" {
+		return "", oneerrors.New(oneerrors.InvalidRequest, "Custom base URL must start with http:// or https://")
+	}
+	if parsed.User != nil {
+		return "", oneerrors.New(oneerrors.InvalidRequest, "Custom base URL must not contain credentials")
+	}
+	return strings.TrimRight(value, "/"), nil
+}
+
+// ProviderBase resolves a catalog Provider or validates a custom endpoint.
+// Built-in Providers may still receive an explicit override, matching the
+// existing CLI behavior.
+func ProviderBase(providerID, customBase string) (string, error) {
+	if providerID == "custom" {
+		return ValidateBaseURL(customBase)
+	}
+	if customBase != "" {
+		return ValidateBaseURL(customBase)
+	}
+	meta, ok := catalog.ProviderByID(providerID)
+	if !ok {
+		return "", oneerrors.New(oneerrors.InvalidRequest, "Provider must be a configured Provider or custom")
+	}
+	return meta.BaseURL, nil
+}
+
+// ProviderConfigBase selects the protocol-specific built-in endpoint. Custom
+// endpoints are left untouched because the user owns their protocol contract.
+func ProviderConfigBase(providerID, customBase, protocol string) (string, error) {
+	base, err := ProviderBase(providerID, customBase)
+	if err != nil {
+		return "", err
+	}
+	if protocol == ProtocolAnthropic && customBase == "" && providerID != "custom" {
+		meta, ok := catalog.ProviderByID(providerID)
+		if ok && meta.AnthropicBaseURL != "" {
+			return meta.AnthropicBaseURL, nil
+		}
+	}
+	return base, nil
+}
+
+func ProviderHome(providerID string) (string, error) {
+	meta, ok := catalog.ProviderByID(providerID)
+	if !ok {
+		return "", oneerrors.New(oneerrors.InvalidRequest, "Registration is only available for a configured Provider")
+	}
+	return meta.Home, nil
+}
+
+func ProtocolForAdapter(adapter string) string {
+	return catalog.ProtocolForAdapter(adapter)
+}
+
+func FallbackProbeModel(providerID string) string {
+	return catalog.FallbackProbeModel(providerID)
+}
+
+func ProtocolLabel(protocol string) string {
+	switch protocol {
+	case ProtocolOpenAI:
+		return "OpenAI Chat Completions"
+	case ProtocolAnthropic:
+		return "Anthropic Messages"
+	case ProtocolResponses:
+		return "OpenAI Responses"
+	default:
+		return protocol
+	}
+}
+
+func OpenAIBaseURL(baseURL string) string {
+	base := strings.TrimRight(baseURL, "/")
+	for _, suffix := range []string{"/chat/completions", "/responses", "/models"} {
+		if before, ok := strings.CutSuffix(base, suffix); ok {
+			base = strings.TrimRight(before, "/")
+			break
+		}
+	}
+	if strings.HasSuffix(base, "/v1") {
+		return base
+	}
+	return base + "/v1"
+}
+
+func AnthropicMessagesURL(baseURL string) string {
+	base := strings.TrimRight(baseURL, "/")
+	for _, suffix := range []string{"/v1/messages", "/messages"} {
+		if before, ok := strings.CutSuffix(base, suffix); ok {
+			base = strings.TrimRight(before, "/")
+			break
+		}
+	}
+	if strings.HasSuffix(base, "/v1") {
+		return base + "/messages"
+	}
+	return base + "/v1/messages"
+}
+
+// PickChatModel keeps provider ordering while skipping IDs that clearly refer
+// to embeddings, rerankers, speech, vision, or other non-chat endpoints.
+func PickChatModel(models []string) string {
+	for _, model := range models {
+		if !nonChatModel.MatchString(model) {
+			return model
+		}
+	}
+	if len(models) > 0 {
+		return models[0]
+	}
+	return ""
+}
+
+func invalidProtocol(protocol string) error {
+	return oneerrors.New(oneerrors.InvalidRequest, fmt.Sprintf("Unknown inference protocol: %s", protocol))
+}
diff --git a/internal/provider/provider_test.go b/internal/provider/provider_test.go
new file mode 100644
index 00000000..8aee87a5
--- /dev/null
+++ b/internal/provider/provider_test.go
@@ -0,0 +1,96 @@
+package provider
+
+import (
+	"reflect"
+	"testing"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+)
+
+func TestValidateBaseURL(t *testing.T) {
+	for _, value := range []string{"", "ftp://example.com", "https:///missing-host", "https://user:pass@example.com", "https://example.com\n"} {
+		if _, err := ValidateBaseURL(value); err == nil {
+			t.Errorf("ValidateBaseURL(%q) unexpectedly succeeded", value)
+		}
+	}
+	got, err := ValidateBaseURL("https://example.com///")
+	if err != nil || got != "https://example.com" {
+		t.Fatalf("ValidateBaseURL() = %q, %v", got, err)
+	}
+}
+
+func TestProviderResolution(t *testing.T) {
+	tests := []struct {
+		provider, custom, protocol, want string
+	}{
+		{"ppio", "", ProtocolOpenAI, "https://api.ppio.com/openai"},
+		{"ppio", "", ProtocolAnthropic, "https://api.ppio.com/anthropic"},
+		{"novita", "", ProtocolAnthropic, "https://api.novita.ai/anthropic"},
+		{"custom", "http://127.0.0.1:9000", ProtocolAnthropic, "http://127.0.0.1:9000"},
+		{"ppio", "https://override.example/", ProtocolAnthropic, "https://override.example"},
+	}
+	for _, test := range tests {
+		got, err := ProviderConfigBase(test.provider, test.custom, test.protocol)
+		if err != nil || got != test.want {
+			t.Errorf("ProviderConfigBase(%q, %q, %q) = %q, %v; want %q", test.provider, test.custom, test.protocol, got, err, test.want)
+		}
+	}
+	if _, err := ProviderBase("custom", ""); err == nil || oneerrors.As(err).Code != oneerrors.InvalidRequest {
+		t.Fatalf("missing custom URL error = %v", err)
+	}
+	if _, err := ProviderHome("custom"); err == nil {
+		t.Fatal("custom registration unexpectedly allowed")
+	}
+}
+
+func TestEndpointNormalizers(t *testing.T) {
+	openAI := map[string]string{
+		"https://example.com/v1/responses":        "https://example.com/v1",
+		"https://example.com/v1/models":           "https://example.com/v1",
+		"https://example.com/v1/chat/completions": "https://example.com/v1",
+		"https://example.com":                     "https://example.com/v1",
+	}
+	for input, want := range openAI {
+		if got := OpenAIBaseURL(input); got != want {
+			t.Errorf("OpenAIBaseURL(%q) = %q, want %q", input, got, want)
+		}
+	}
+	anthropic := map[string]string{
+		"https://api.ppio.com/anthropic":  "https://api.ppio.com/anthropic/v1/messages",
+		"https://proxy.test/v1":           "https://proxy.test/v1/messages",
+		"https://proxy.test/v1/messages":  "https://proxy.test/v1/messages",
+		"https://proxy.test/messages":     "https://proxy.test/v1/messages",
+		"https://proxy.test/anthropic///": "https://proxy.test/anthropic/v1/messages",
+	}
+	for input, want := range anthropic {
+		if got := AnthropicMessagesURL(input); got != want {
+			t.Errorf("AnthropicMessagesURL(%q) = %q, want %q", input, got, want)
+		}
+	}
+}
+
+func TestProtocolAndModelProjection(t *testing.T) {
+	if ProtocolForAdapter("codex") != ProtocolResponses || ProtocolForAdapter("claude-code") != ProtocolAnthropic || ProtocolForAdapter("new") != ProtocolOpenAI {
+		t.Fatal("adapter protocol projection diverged")
+	}
+	if ProtocolLabel(ProtocolResponses) != "OpenAI Responses" || ProtocolLabel("future") != "future" {
+		t.Fatal("protocol labels diverged")
+	}
+	got := []string{
+		PickChatModel([]string{"whisper-large-v3", "bge-reranker-v2", "deepseek-v3", "gpt-5.6-terra"}),
+		PickChatModel([]string{"resolver-1", "evolve-chat"}),
+	}
+	if !reflect.DeepEqual(got, []string{"deepseek-v3", "resolver-1"}) {
+		t.Fatalf("PickChatModel() = %v", got)
+	}
+	if PickChatModel([]string{"text-embedding-3-small", "whisper-1"}) != "text-embedding-3-small" {
+		t.Fatal("all non-chat models should fall back to the first ID")
+	}
+}
+
+func TestInvalidProtocolErrorIsStable(t *testing.T) {
+	err := invalidProtocol("grpc")
+	if oneerrors.As(err).Code != oneerrors.InvalidRequest || err.Error() != "Unknown inference protocol: grpc" {
+		t.Fatalf("invalid protocol error = %v", err)
+	}
+}
diff --git a/internal/provider/store.go b/internal/provider/store.go
new file mode 100644
index 00000000..dda3dccc
--- /dev/null
+++ b/internal/provider/store.go
@@ -0,0 +1,236 @@
+package provider
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/MaimoryLab/OneAgent/internal/catalog"
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+const userProviderSchemaVersion = 1
+
+var userProviderIDPattern = regexp.MustCompile(`^[a-z0-9][a-z0-9-]{0,63}$`)
+
+// Entry is the editable local Provider record. APIKey is returned only by the
+// explicit Provider CRUD service; status projections expose HasKey instead.
+type Entry struct {
+	ID               string `json:"id"`
+	Name             string `json:"name"`
+	Home             string `json:"home"`
+	BaseURL          string `json:"base_url"`
+	AnthropicBaseURL string `json:"anthropic_base_url"`
+	APIKey           string `json:"api_key"`
+	BuiltIn          bool   `json:"built_in"`
+	FallbackModel    string `json:"-"`
+}
+
+type storedProvider struct {
+	Name             string `json:"name"`
+	Home             string `json:"home,omitempty"`
+	BaseURL          string `json:"base_url"`
+	AnthropicBaseURL string `json:"anthropic_base_url,omitempty"`
+	APIKey           string `json:"api_key,omitempty"`
+}
+
+type userProviderFile struct {
+	SchemaVersion int                       `json:"schema_version"`
+	Providers     map[string]storedProvider `json:"providers"`
+}
+
+type Store struct {
+	home       string
+	filesystem securefs.Store
+}
+
+func NewStore(home string, filesystem securefs.Store) Store {
+	return Store{home: home, filesystem: filesystem}
+}
+
+func (s Store) Path() string {
+	return filepath.Join(s.home, ".oneagent", "providers.json")
+}
+
+func (s Store) Get(id string) (Entry, error) {
+	id = strings.TrimSpace(id)
+	file, err := s.load()
+	if err != nil {
+		return Entry{}, err
+	}
+	if saved, ok := file.Providers[id]; ok {
+		_, builtIn := catalog.ProviderByID(id)
+		return entryFromStored(id, saved, builtIn), nil
+	}
+	if builtIn, ok := catalog.ProviderByID(id); ok {
+		return Entry{
+			ID: id, Name: builtIn.Name, Home: builtIn.Home, BaseURL: builtIn.BaseURL,
+			AnthropicBaseURL: builtIn.AnthropicBaseURL, BuiltIn: true,
+			FallbackModel: catalog.FallbackProbeModel(id),
+		}, nil
+	}
+	return Entry{}, oneerrors.New(oneerrors.InvalidRequest, "Unknown Provider: "+id)
+}
+
+func (s Store) Resolve(id, explicitBase string) (Entry, error) {
+	id = strings.TrimSpace(id)
+	if id == "custom" {
+		base, err := ValidateBaseURL(strings.TrimSpace(explicitBase))
+		if err != nil {
+			return Entry{}, err
+		}
+		return Entry{ID: id, Name: "Custom", BaseURL: base, FallbackModel: catalog.FallbackProbeModel(id)}, nil
+	}
+	entry, err := s.Get(id)
+	if err != nil {
+		return Entry{}, err
+	}
+	if strings.TrimSpace(explicitBase) != "" {
+		entry.BaseURL, err = ValidateBaseURL(strings.TrimSpace(explicitBase))
+		entry.AnthropicBaseURL = ""
+	}
+	return entry, err
+}
+
+func (entry Entry) BaseFor(protocol string) string {
+	if protocol == ProtocolAnthropic && entry.AnthropicBaseURL != "" {
+		return entry.AnthropicBaseURL
+	}
+	return entry.BaseURL
+}
+
+func (s Store) Public() (map[string]catalog.Provider, error) {
+	result := catalog.PublicProviders()
+	file, err := s.load()
+	if err != nil {
+		return nil, err
+	}
+	for id, saved := range file.Providers {
+		_, builtIn := catalog.ProviderByID(id)
+		result[id] = catalog.Provider{
+			Name: saved.Name, Home: saved.Home, BaseURL: saved.BaseURL,
+			AnthropicBaseURL: saved.AnthropicBaseURL, Custom: !builtIn, HasKey: saved.APIKey != "",
+		}
+	}
+	return result, nil
+}
+
+func (s Store) Save(ctx context.Context, entry Entry) (Entry, error) {
+	entry.ID = strings.TrimSpace(entry.ID)
+	entry.Name = strings.TrimSpace(entry.Name)
+	entry.Home = strings.TrimSpace(entry.Home)
+	entry.BaseURL = strings.TrimSpace(entry.BaseURL)
+	entry.AnthropicBaseURL = strings.TrimSpace(entry.AnthropicBaseURL)
+	if err := validateEntry(entry); err != nil {
+		return Entry{}, err
+	}
+	file, err := s.load()
+	if err != nil {
+		return Entry{}, err
+	}
+	file.Providers[entry.ID] = storedProvider{
+		Name: entry.Name, Home: entry.Home, BaseURL: entry.BaseURL,
+		AnthropicBaseURL: entry.AnthropicBaseURL, APIKey: entry.APIKey,
+	}
+	if err := s.write(ctx, file); err != nil {
+		return Entry{}, err
+	}
+	_, entry.BuiltIn = catalog.ProviderByID(entry.ID)
+	entry.FallbackModel = catalog.FallbackProbeModel(entry.ID)
+	return entry, nil
+}
+
+func (s Store) SaveKey(ctx context.Context, id, apiKey string) error {
+	if id == "custom" || apiKey == "" {
+		return nil
+	}
+	entry, err := s.Get(id)
+	if err != nil {
+		return err
+	}
+	if entry.APIKey == apiKey {
+		return nil
+	}
+	entry.APIKey = apiKey
+	_, err = s.Save(ctx, entry)
+	return err
+}
+
+func (s Store) Delete(ctx context.Context, id string) error {
+	id = strings.TrimSpace(id)
+	file, err := s.load()
+	if err != nil {
+		return err
+	}
+	if _, ok := file.Providers[id]; !ok {
+		return oneerrors.New(oneerrors.InvalidRequest, "Unknown Provider: "+id)
+	}
+	delete(file.Providers, id)
+	return s.write(ctx, file)
+}
+
+func (s Store) load() (userProviderFile, error) {
+	file := userProviderFile{SchemaVersion: userProviderSchemaVersion, Providers: map[string]storedProvider{}}
+	data, err := os.ReadFile(s.Path())
+	if os.IsNotExist(err) {
+		return file, nil
+	}
+	if err != nil {
+		return file, oneerrors.New(oneerrors.ConfigWriteFailed, fmt.Sprintf("Cannot read saved Providers: %v", err))
+	}
+	if err := json.Unmarshal(data, &file); err != nil || file.SchemaVersion != userProviderSchemaVersion || file.Providers == nil {
+		return userProviderFile{}, oneerrors.New(oneerrors.InvalidRequest, "Saved Provider file is invalid")
+	}
+	for id, saved := range file.Providers {
+		_, builtIn := catalog.ProviderByID(id)
+		if err := validateEntry(entryFromStored(id, saved, builtIn)); err != nil {
+			return userProviderFile{}, oneerrors.New(oneerrors.InvalidRequest, "Saved Provider file is invalid")
+		}
+	}
+	return file, nil
+}
+
+func (s Store) write(ctx context.Context, file userProviderFile) error {
+	data, err := json.MarshalIndent(file, "", "  ")
+	if err != nil {
+		return oneerrors.New(oneerrors.ConfigWriteFailed, "Cannot encode saved Providers")
+	}
+	_, err = s.filesystem.AtomicWrite(ctx, s.Path(), append(data, '\n'), true)
+	return err
+}
+
+func validateEntry(entry Entry) error {
+	if !userProviderIDPattern.MatchString(entry.ID) || entry.ID == "custom" {
+		return oneerrors.New(oneerrors.InvalidRequest, "Provider ID must use lowercase letters, digits, or '-' and cannot be custom")
+	}
+	if entry.Name == "" {
+		return oneerrors.New(oneerrors.InvalidRequest, "Provider name is required")
+	}
+	if _, err := ValidateBaseURL(entry.BaseURL); err != nil {
+		return err
+	}
+	if entry.Home != "" {
+		if _, err := ValidateBaseURL(entry.Home); err != nil {
+			return oneerrors.New(oneerrors.InvalidRequest, "Provider home URL is invalid")
+		}
+	}
+	if entry.AnthropicBaseURL != "" {
+		if _, err := ValidateBaseURL(entry.AnthropicBaseURL); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func entryFromStored(id string, saved storedProvider, builtIn bool) Entry {
+	return Entry{
+		ID: id, Name: saved.Name, Home: saved.Home, BaseURL: saved.BaseURL,
+		AnthropicBaseURL: saved.AnthropicBaseURL, APIKey: saved.APIKey, BuiltIn: builtIn,
+		FallbackModel: catalog.FallbackProbeModel(id),
+	}
+}
diff --git a/internal/provider/store_test.go b/internal/provider/store_test.go
new file mode 100644
index 00000000..4bc5e179
--- /dev/null
+++ b/internal/provider/store_test.go
@@ -0,0 +1,45 @@
+package provider
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/MaimoryLab/OneAgent/internal/securefs"
+)
+
+func TestStorePersistsCRUDAndPrivateKey(t *testing.T) {
+	home := t.TempDir()
+	store := NewStore(home, securefs.New(securefs.Options{OS: "linux"}))
+	want := Entry{
+		ID: "acme", Name: "Acme", Home: "https://acme.test/",
+		BaseURL: "https://api.acme.test/openai", AnthropicBaseURL: "https://api.acme.test/anthropic",
+		APIKey: "sk-persisted",
+	}
+	if _, err := store.Save(context.Background(), want); err != nil {
+		t.Fatal(err)
+	}
+	info, err := os.Stat(store.Path())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Mode().Perm() != 0o600 {
+		t.Fatalf("provider file mode = %v", info.Mode().Perm())
+	}
+
+	reloaded := NewStore(home, securefs.New(securefs.Options{OS: "linux"}))
+	got, err := reloaded.Get("acme")
+	if err != nil || got.APIKey != want.APIKey || got.BaseURL != want.BaseURL || got.BuiltIn {
+		t.Fatalf("reloaded Provider = %#v, err=%v", got, err)
+	}
+	public, err := reloaded.Public()
+	if err != nil || !public["acme"].Custom || !public["acme"].HasKey {
+		t.Fatalf("public Providers = %#v, err=%v", public, err)
+	}
+	if err := reloaded.Delete(context.Background(), "acme"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := reloaded.Get("acme"); err == nil {
+		t.Fatal("deleted Provider was still readable")
+	}
+}
diff --git a/internal/securefs/securefs.go b/internal/securefs/securefs.go
new file mode 100644
index 00000000..0d996fef
--- /dev/null
+++ b/internal/securefs/securefs.go
@@ -0,0 +1,329 @@
+// Package securefs contains the small filesystem primitives used by profile
+// and configuration writers. It deliberately does not know about any file
+// format or credential name.
+package securefs
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"os/user"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"time"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+)
+
+// CommandRunner is injectable so Windows ACL behavior can be tested without
+// invoking a host command. argv[0] is the executable name.
+type CommandRunner func(context.Context, []string) error
+
+// SecurePathFunc is an optional security hook used by fault-injection tests.
+// The default implementation applies Unix modes or Windows ACLs.
+type SecurePathFunc func(path string, directory bool) error
+
+type Options struct {
+	OS       string
+	Username string
+	Now      func() time.Time
+	Run      CommandRunner
+	Secure   SecurePathFunc
+}
+
+type Store struct {
+	os            string
+	username      string
+	now           func() time.Time
+	commandRunner CommandRunner
+	secure        SecurePathFunc
+}
+
+func New(options Options) Store {
+	platformID := options.OS
+	if platformID == "" {
+		platformID = runtime.GOOS
+	}
+	if options.Now == nil {
+		options.Now = time.Now
+	}
+	if options.Run == nil {
+		options.Run = runCommand
+	}
+	return Store{
+		os:            platformID,
+		username:      options.Username,
+		now:           options.Now,
+		commandRunner: options.Run,
+		secure:        options.Secure,
+	}
+}
+
+func (s Store) EnsurePrivateDir(ctx context.Context, path string) error {
+	if err := checkContext(ctx); err != nil {
+		return err
+	}
+	if path == "" {
+		return writeError("Cannot secure an empty directory path")
+	}
+	if err := os.MkdirAll(path, 0o700); err != nil {
+		return writeError("Cannot create private directory %s: %v", path, err)
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		return writeError("Cannot inspect private directory %s: %v", path, err)
+	}
+	if !info.IsDir() {
+		return writeError("Private path %s is not a directory", path)
+	}
+	if err := s.securePath(ctx, path, true); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (s Store) SecureFile(ctx context.Context, path string) error {
+	if err := checkContext(ctx); err != nil {
+		return err
+	}
+	if path == "" {
+		return writeError("Cannot secure an empty file path")
+	}
+	if err := s.securePath(ctx, path, false); err != nil {
+		return err
+	}
+	return nil
+}
+
+// Backup copies an existing file beside itself. A missing source is not an
+// error and returns an empty path. Callers decide whether the backup is a
+// secret and therefore needs an additional permission check.
+func (s Store) Backup(ctx context.Context, path string) (string, error) {
+	if err := checkContext(ctx); err != nil {
+		return "", err
+	}
+	info, err := os.Stat(path)
+	if os.IsNotExist(err) {
+		return "", nil
+	}
+	if err != nil {
+		return "", writeError("Cannot inspect %s before backup: %v", path, err)
+	}
+	if info.IsDir() {
+		return "", writeError("Cannot back up directory %s", path)
+	}
+	candidate := s.backupName(path)
+	if err := copyFile(path, candidate, info.Mode().Perm()); err != nil {
+		return "", writeError("Cannot back up %s: %v", path, err)
+	}
+	return candidate, nil
+}
+
+// AtomicWrite publishes content only after the temporary file has been
+// written, synced, and secured. The temporary inode always lives beside the
+// target so a successful rename cannot cross filesystems.
+func (s Store) AtomicWrite(ctx context.Context, path string, content []byte, secret bool) (backup string, err error) {
+	if err = checkContext(ctx); err != nil {
+		return "", err
+	}
+	parent := filepath.Dir(path)
+	if err = s.EnsurePrivateDir(ctx, parent); err != nil {
+		return "", err
+	}
+	backup, err = s.Backup(ctx, path)
+	if err != nil {
+		return "", err
+	}
+	if backup != "" && secret {
+		if err = s.SecureFile(ctx, backup); err != nil {
+			if removeErr := os.Remove(backup); removeErr != nil {
+				return "", writeError("Cannot remove insecure secret backup %s: %v", backup, removeErr)
+			}
+			return "", err
+		}
+	}
+
+	temporary, err := os.CreateTemp(parent, ".oneagent-tmp-")
+	if err != nil {
+		return backup, writeError("Cannot create temporary file for %s: %v", path, err)
+	}
+	temporaryPath := temporary.Name()
+	cleanup := func() error {
+		_ = temporary.Close()
+		if removeErr := os.Remove(temporaryPath); removeErr != nil && !os.IsNotExist(removeErr) {
+			return writeError("Cannot remove temporary %sfile %s: %v", secretWord(secret), temporaryPath, removeErr)
+		}
+		return nil
+	}
+	defer func() {
+		if cleanupErr := cleanup(); err == nil && cleanupErr != nil {
+			err = cleanupErr
+		}
+	}()
+
+	if _, err = temporary.Write(content); err != nil {
+		return backup, writeError("Cannot write temporary file for %s: %v", path, err)
+	}
+	if err = temporary.Sync(); err != nil {
+		return backup, writeError("Cannot flush temporary file for %s: %v", path, err)
+	}
+	if err = temporary.Close(); err != nil {
+		return backup, writeError("Cannot close temporary file for %s: %v", path, err)
+	}
+	if err = s.SecureFile(ctx, temporaryPath); err != nil {
+		return backup, err
+	}
+	if err = checkContext(ctx); err != nil {
+		return backup, err
+	}
+	if err = os.Rename(temporaryPath, path); err != nil {
+		return backup, writeError("Cannot replace %s: %v", path, err)
+	}
+	return backup, nil
+}
+
+func (s Store) securePath(ctx context.Context, path string, directory bool) error {
+	if err := checkContext(ctx); err != nil {
+		return err
+	}
+	if s.secure != nil {
+		if err := s.secure(path, directory); err != nil {
+			return err
+		}
+		return nil
+	}
+	if s.os != "windows" {
+		mode := os.FileMode(0o600)
+		if directory {
+			mode = 0o700
+		}
+		if err := os.Chmod(path, mode); err != nil {
+			return writeError("Cannot secure %s: %v", path, err)
+		}
+		return nil
+	}
+	username := s.username
+	if username == "" {
+		username = os.Getenv("USERNAME")
+	}
+	if username == "" {
+		if current, err := user.Current(); err == nil {
+			username = current.Username
+		}
+	}
+	if username == "" {
+		return writeError("Cannot secure %s: Windows username is unavailable", path)
+	}
+	grants := username + ":F"
+	system := "*S-1-5-18:F"
+	if directory {
+		grants = username + ":(OI)(CI)F"
+		system = "*S-1-5-18:(OI)(CI)F"
+	}
+	for _, argv := range [][]string{
+		{"icacls", path, "/reset"},
+		{"icacls", path, "/inheritance:r", "/grant:r", grants, system},
+	} {
+		if err := s.execute(ctx, argv); err != nil {
+			if ctx.Err() != nil {
+				return checkContext(ctx)
+			}
+			return writeError("Failed to secure Windows ACL for %s", path)
+		}
+	}
+	return nil
+}
+
+func (s Store) backupName(path string) string {
+	now := s.now
+	if now == nil {
+		now = time.Now
+	}
+	stamp := now().UTC().Format("20060102150405")
+	base := path + ".backup-" + stamp
+	candidate := base
+	for counter := 1; ; counter++ {
+		if _, err := os.Lstat(candidate); os.IsNotExist(err) {
+			return candidate
+		}
+		candidate = fmt.Sprintf("%s-%d", base, counter)
+	}
+}
+
+func (s Store) execute(ctx context.Context, argv []string) error {
+	if err := checkContext(ctx); err != nil {
+		return err
+	}
+	if s.commandRunner == nil {
+		return runCommand(ctx, argv)
+	}
+	return s.commandRunner(ctx, argv)
+}
+
+func runCommand(ctx context.Context, argv []string) error {
+	if len(argv) == 0 || strings.TrimSpace(argv[0]) == "" {
+		return fmt.Errorf("empty command")
+	}
+	command := exec.CommandContext(ctx, argv[0], argv[1:]...)
+	command.Stdout = io.Discard
+	command.Stderr = io.Discard
+	return command.Run()
+}
+
+func copyFile(source, destination string, mode os.FileMode) error {
+	input, err := os.Open(source)
+	if err != nil {
+		return err
+	}
+	defer input.Close()
+	output, err := os.OpenFile(destination, os.O_WRONLY|os.O_CREATE|os.O_EXCL, mode)
+	if err != nil {
+		return err
+	}
+	closeOutput := func() error {
+		if closeErr := output.Close(); closeErr != nil {
+			return closeErr
+		}
+		return nil
+	}
+	if _, err = io.Copy(output, input); err != nil {
+		_ = output.Close()
+		_ = os.Remove(destination)
+		return err
+	}
+	if err = output.Sync(); err != nil {
+		_ = output.Close()
+		_ = os.Remove(destination)
+		return err
+	}
+	if err = os.Chmod(destination, mode); err != nil {
+		_ = output.Close()
+		_ = os.Remove(destination)
+		return err
+	}
+	return closeOutput()
+}
+
+func checkContext(ctx context.Context) error {
+	if ctx == nil {
+		return nil
+	}
+	if err := ctx.Err(); err != nil {
+		return oneerrors.New(oneerrors.Timeout, "Filesystem request was cancelled", oneerrors.WithRetryable(true), oneerrors.WithCause(err))
+	}
+	return nil
+}
+
+func writeError(format string, values ...any) error {
+	return oneerrors.New(oneerrors.ConfigWriteFailed, fmt.Sprintf(format, values...))
+}
+
+func secretWord(secret bool) string {
+	if secret {
+		return "secret "
+	}
+	return ""
+}
diff --git a/internal/securefs/securefs_test.go b/internal/securefs/securefs_test.go
new file mode 100644
index 00000000..00212328
--- /dev/null
+++ b/internal/securefs/securefs_test.go
@@ -0,0 +1,175 @@
+package securefs
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	oneerrors "github.com/MaimoryLab/OneAgent/internal/errors"
+)
+
+func fixedClock() time.Time {
+	return time.Date(2026, time.July, 30, 12, 34, 56, 0, time.UTC)
+}
+
+func TestAtomicWriteCreatesPrivateFileAndCollisionSafeBackup(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, ".oneagent", "profile.json")
+	if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(target, []byte("old"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	store := New(Options{OS: "linux", Now: fixedClock})
+	backupPath, err := store.AtomicWrite(context.Background(), target, []byte("new"), true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if backupPath != target+".backup-20260730123456" {
+		t.Fatalf("backup path = %q", backupPath)
+	}
+	assertMode(t, filepath.Dir(target), 0o700)
+	assertMode(t, target, 0o600)
+	assertMode(t, backupPath, 0o600)
+	if got, _ := os.ReadFile(target); string(got) != "new" {
+		t.Fatalf("target content = %q", got)
+	}
+	if got, _ := os.ReadFile(backupPath); string(got) != "old" {
+		t.Fatalf("backup content = %q", got)
+	}
+	if err := os.WriteFile(target+".backup-20260730123456", []byte("collision"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := store.AtomicWrite(context.Background(), target, []byte("newer"), false); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(target + ".backup-20260730123456-1"); err != nil {
+		t.Fatalf("collision backup missing: %v", err)
+	}
+}
+
+func TestSecretBackupSecurityFailureRemovesBackup(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, "secret")
+	if err := os.WriteFile(target, []byte("old"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	store := New(Options{
+		OS:  "linux",
+		Now: fixedClock,
+		Secure: func(path string, directory bool) error {
+			if !directory && strings.Contains(path, ".backup-") {
+				return oneerrors.New(oneerrors.ConfigWriteFailed, "backup ACL failed")
+			}
+			return nil
+		},
+	})
+	_, err := store.AtomicWrite(context.Background(), target, []byte("new"), true)
+	if err == nil || !strings.Contains(err.Error(), "backup ACL failed") {
+		t.Fatalf("security failure = %v", err)
+	}
+	matches, _ := filepath.Glob(target + ".backup-*")
+	if len(matches) != 0 {
+		t.Fatalf("insecure backups remain: %v", matches)
+	}
+	if got, _ := os.ReadFile(target); string(got) != "old" {
+		t.Fatalf("original changed after security failure: %q", got)
+	}
+}
+
+func TestTemporarySecurityFailureLeavesNoPublishedReplacement(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, ".oneagent", "new")
+	callCount := 0
+	store := New(Options{
+		OS:  "linux",
+		Now: fixedClock,
+		Secure: func(path string, directory bool) error {
+			if !directory {
+				callCount++
+				if callCount == 1 {
+					return oneerrors.New(oneerrors.ConfigWriteFailed, "temporary ACL failed")
+				}
+			}
+			return nil
+		},
+	})
+	_, err := store.AtomicWrite(context.Background(), target, []byte("replacement"), false)
+	if err == nil || !strings.Contains(err.Error(), "temporary ACL failed") {
+		t.Fatalf("temporary failure = %v", err)
+	}
+	if _, statErr := os.Stat(target); !os.IsNotExist(statErr) {
+		t.Fatalf("replacement was published: %v", statErr)
+	}
+	entries, readErr := os.ReadDir(filepath.Dir(target))
+	if readErr != nil {
+		t.Fatal(readErr)
+	}
+	for _, entry := range entries {
+		if strings.HasPrefix(entry.Name(), ".oneagent-tmp-") {
+			t.Fatalf("temporary file remains: %s", entry.Name())
+		}
+	}
+}
+
+func TestWindowsACLCommandsAreRestrictedAndContextAware(t *testing.T) {
+	var calls [][]string
+	store := New(Options{
+		OS:       "windows",
+		Username: "tester",
+		Run: func(_ context.Context, argv []string) error {
+			calls = append(calls, append([]string(nil), argv...))
+			return nil
+		},
+	})
+	root := t.TempDir()
+	if err := os.MkdirAll(root, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := store.SecureFile(context.Background(), filepath.Join(root, "secret.ps1")); err != nil {
+		t.Fatal(err)
+	}
+	if err := store.EnsurePrivateDir(context.Background(), filepath.Join(root, "nested")); err != nil {
+		t.Fatal(err)
+	}
+	if len(calls) != 4 {
+		t.Fatalf("ACL calls = %v", calls)
+	}
+	if !reflect.DeepEqual(calls[0], []string{"icacls", filepath.Join(root, "secret.ps1"), "/reset"}) || !reflect.DeepEqual(calls[1], []string{"icacls", filepath.Join(root, "secret.ps1"), "/inheritance:r", "/grant:r", "tester:F", "*S-1-5-18:F"}) {
+		t.Fatalf("file ACL calls = %v", calls[:2])
+	}
+	if !strings.Contains(strings.Join(calls[3], " "), "tester:(OI)(CI)F") {
+		t.Fatalf("directory ACL grant = %v", calls[3])
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if err := store.SecureFile(ctx, filepath.Join(root, "cancelled")); err == nil || oneerrors.As(err).Code != oneerrors.Timeout {
+		t.Fatalf("cancelled ACL = %v", err)
+	}
+}
+
+func TestAtomicWriteMapsFilesystemFailuresAndDoesNotLeakContent(t *testing.T) {
+	store := New(Options{OS: "linux"})
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err := store.AtomicWrite(ctx, filepath.Join(t.TempDir(), "missing", "target"), []byte("secret-value"), false)
+	if err == nil || oneerrors.As(err).Code != oneerrors.Timeout || strings.Contains(err.Error(), "secret-value") {
+		t.Fatalf("cancelled filesystem request = %v", err)
+	}
+}
+
+func assertMode(t *testing.T, path string, want os.FileMode) {
+	t.Helper()
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := info.Mode().Perm(); got != want {
+		t.Fatalf("%s mode = %o, want %o", path, got, want)
+	}
+}
diff --git a/internal/version/version.go b/internal/version/version.go
new file mode 100644
index 00000000..4ffe79d5
--- /dev/null
+++ b/internal/version/version.go
@@ -0,0 +1,6 @@
+// Package version holds the single version constant reported by the Go CLI and
+// the desktop shell.
+package version
+
+// Version is the current native Go/Wails release line.
+const Version = "0.3.0-dev"
diff --git a/manifest_embed.go b/manifest_embed.go
new file mode 100644
index 00000000..2c572893
--- /dev/null
+++ b/manifest_embed.go
@@ -0,0 +1,37 @@
+// Package oneagent is the module root. It exists to embed the catalog files
+// and the built frontend bundle shared by the CLI and desktop shell.
+package oneagent
+
+import "embed"
+
+// AgentLockManifest contains the repository's hand-edited catalog files.
+// Keeping the embed at the module root lets internal packages use them without
+// maintaining a second hand-edited copy inside a package.
+//
+//go:embed agents.lock.json providers.lock.json runtimes.lock.json
+var AgentLockManifest embed.FS
+
+// FrontendAssets is the asset tree consumed by the Wails shell. The checked-in
+// .keep file makes the stage-0 shell buildable before Vite has produced dist;
+// the build task replaces that directory with the real bundle.
+//
+//go:embed all:frontend/dist
+var FrontendAssets embed.FS
+
+// EmbeddedAgentLock returns a fresh copy of agents.lock.json for parsers and
+// callers that need to retain or modify the returned bytes.
+func EmbeddedAgentLock() ([]byte, error) {
+	return AgentLockManifest.ReadFile("agents.lock.json")
+}
+
+// EmbeddedProviderLock returns a fresh copy of providers.lock.json for the
+// catalog parser.
+func EmbeddedProviderLock() ([]byte, error) {
+	return AgentLockManifest.ReadFile("providers.lock.json")
+}
+
+// EmbeddedRuntimeLock returns a fresh copy of runtimes.lock.json, the pinned
+// Node.js and uv download contract used to bootstrap package managers.
+func EmbeddedRuntimeLock() ([]byte, error) {
+	return AgentLockManifest.ReadFile("runtimes.lock.json")
+}
diff --git a/oneagent/__init__.py b/oneagent/__init__.py
deleted file mode 100644
index 3be20612..00000000
--- a/oneagent/__init__.py
+++ /dev/null
@@ -1,3 +0,0 @@
-"""OneAgent cross-platform installer core."""
-
-__version__ = "0.2.0-dev"
diff --git a/oneagent/catalog.py b/oneagent/catalog.py
deleted file mode 100644
index 104b736e..00000000
--- a/oneagent/catalog.py
+++ /dev/null
@@ -1,226 +0,0 @@
-from __future__ import annotations
-
-import json
-import os
-import platform
-import sys
-from pathlib import Path
-from typing import Any
-
-from .errors import OneAgentError
-
-
-PROVIDERS = {
-    "ppio": {
-        "name": "PPIO",
-        "home": "https://ppio.com/",
-        "base_url": "https://api.ppio.com/openai",
-        "anthropic_base_url": "https://api.ppio.com/anthropic",
-        # Last-resort probe model, used only when the endpoint's model list
-        # cannot be fetched (resolve_probe_model normally picks a live ID).
-        # It must still exist on this provider; staleness degrades only this
-        # narrow fallback path. The IDs differ per provider (PPIO publishes
-        # deepseek-v3, Novita deepseek_v3), so this cannot be one shared
-        # constant.
-        "fallback_probe_model": "deepseek/deepseek-v3",
-    },
-    "novita": {
-        "name": "Novita",
-        "home": "https://novita.ai/",
-        "base_url": "https://api.novita.ai/openai",
-        "anthropic_base_url": "https://api.novita.ai/anthropic",
-        "fallback_probe_model": "deepseek/deepseek_v3",
-    },
-}
-
-
-def fallback_probe_model(provider: str) -> str:
-    """Last-resort probe model when the endpoint's model list is unavailable.
-
-    Normal probes resolve a live model through resolve_probe_model(); this
-    covers only the narrow path where discovery fails. Custom endpoints get
-    the most widely published ID as a best guess; the user can always run the
-    probe again after selecting a real model.
-    """
-    meta = PROVIDERS.get(provider)
-    if meta:
-        return str(meta["fallback_probe_model"])
-    return "deepseek/deepseek-v3"
-
-AGENT_GROUPS = [
-    {"id": "auto", "name": "One-click configurable"},
-    {"id": "gateway", "name": "Gateway agents"},
-    {"id": "platform", "name": "Official account agents"},
-    {"id": "ide", "name": "IDE extensions"},
-]
-
-PROTOCOL_OPENAI = "openai"
-PROTOCOL_ANTHROPIC = "anthropic"
-PROTOCOL_RESPONSES = "responses"
-
-# Which inference protocol each Agent speaks once configured. A model ID that
-# answers one protocol is not guaranteed to answer the others, so this drives
-# both the connection test and the config write.
-ADAPTER_PROTOCOLS = {
-    "codex": PROTOCOL_RESPONSES,
-    "claude-code": PROTOCOL_ANTHROPIC,
-    "opencode": PROTOCOL_OPENAI,
-    "kilo-cli": PROTOCOL_OPENAI,
-    "aider": PROTOCOL_OPENAI,
-}
-
-
-def agent_protocol(adapter: str) -> str:
-    return ADAPTER_PROTOCOLS.get(adapter, PROTOCOL_OPENAI)
-
-
-# Package registries a user may install from when the official one is not
-# reachable. The product boundary allows an authorised mirror (priority 2 in the
-# software-acquisition policy) provided it carries a licence, a pinned version,
-# a checksum and the upstream address -- so each entry records its upstream, and
-# install_locked_agent verifies the manifest's integrity value against whatever
-# the mirror served.
-#
-# This changes where a package is fetched from, not how the user reaches the
-# network: OneAgent opens no tunnel and forwards no traffic, which is what
-# separates it from the proxying the boundary forbids. Nothing here may point at
-# storage OneAgent operates -- redistributing a proprietary Agent needs a
-# licence that pointing at a public read-only mirror does not.
-OFFICIAL_NPM_REGISTRY = "https://registry.npmjs.org/"
-
-PACKAGE_MIRRORS = {
-    "official": {
-        "name": "官方源",
-        "registry": OFFICIAL_NPM_REGISTRY,
-        "upstream": OFFICIAL_NPM_REGISTRY,
-        "note": "npm 官方 registry，默认使用。",
-    },
-    "npmmirror": {
-        "name": "npmmirror（阿里云）",
-        "registry": "https://registry.npmmirror.com/",
-        "upstream": OFFICIAL_NPM_REGISTRY,
-        "note": "官方源的公开只读镜像，包体与校验值均与官方一致；官方源不可达时可用。",
-    },
-}
-
-
-def public_mirrors() -> list[dict[str, str]]:
-    """Mirror choices for the UI, upstream included so the origin is visible."""
-    return [
-        {
-            "id": mirror_id,
-            "name": str(meta["name"]),
-            "registry": str(meta["registry"]),
-            "upstream": str(meta["upstream"]),
-            "note": str(meta["note"]),
-        }
-        for mirror_id, meta in PACKAGE_MIRRORS.items()
-    ]
-
-
-def resource_root() -> Path:
-    """Locate agents.lock.json and the built frontend across all three layouts.
-
-    A source checkout keeps them beside the package, PyInstaller unpacks them
-    into _MEIPASS, and a wheel carries them inside the package because only
-    files under the package directory survive installation. The checkout is
-    checked first so a stale staging directory left behind by a local wheel
-    build can never shadow the real manifest.
-    """
-    bundle_root = getattr(sys, "_MEIPASS", None)
-    if bundle_root:
-        return Path(bundle_root)
-    module_dir = Path(__file__).resolve().parent
-    checkout = module_dir.parent
-    if (checkout / "agents.lock.json").is_file():
-        return checkout
-    return module_dir / "_resources"
-
-
-def load_manifest(path: Path | None = None) -> dict[str, Any]:
-    manifest_path = path or resource_root() / "agents.lock.json"
-    try:
-        data = json.loads(manifest_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        raise OneAgentError("INVALID_REQUEST", f"Cannot load Agent lock manifest: {exc}") from exc
-    if data.get("schema_version") != 1 or not isinstance(data.get("agents"), dict):
-        raise OneAgentError("INVALID_REQUEST", "Unsupported Agent lock manifest schema")
-    return data
-
-
-def agent_catalog() -> dict[str, dict[str, Any]]:
-    return load_manifest()["agents"]
-
-
-def public_providers() -> dict[str, dict[str, str]]:
-    """Provider fields the API exposes.
-
-    PROVIDERS also carries internals such as the fallback probe model. Sending
-    the constant wholesale leaked those into /api/status the moment one was
-    added, so project the public fields explicitly instead.
-    """
-    public: dict[str, dict[str, str]] = {}
-    for provider_id, meta in PROVIDERS.items():
-        entry = {"name": str(meta["name"]), "home": str(meta["home"]), "base_url": str(meta["base_url"])}
-        anthropic = meta.get("anthropic_base_url")
-        if anthropic:
-            entry["anthropic_base_url"] = str(anthropic)
-        public[provider_id] = entry
-    return public
-
-
-def public_catalog() -> list[dict[str, object]]:
-    items = []
-    for agent_id, meta in agent_catalog().items():
-        items.append(
-            {
-                "id": agent_id,
-                "name": meta["name"],
-                "group": meta["group"],
-                "configMode": meta["config_mode"],
-                "guideOnly": meta["config_mode"] == "guide",
-                "lockedVersion": (meta.get("package") or {}).get("version"),
-                "protocol": (
-                    agent_protocol(str(meta.get("config_adapter") or ""))
-                    if meta["config_mode"] == "auto"
-                    else None
-                ),
-                "platforms": meta.get("platforms", []),
-                "platformNote": meta.get("windows_note", "") if current_platform()["os"] == "windows" else "",
-                # How prominently to show it, independent of whether OneAgent can
-                # install it: an overview is judged by whether the tools people
-                # actually use are on it.
-                "rank": meta.get("rank", 99),
-            }
-        )
-    # Sorted here so every client shows the same order without re-deriving it.
-    return sorted(items, key=lambda item: (item["rank"], str(item["id"])))
-
-
-def current_platform() -> dict[str, str]:
-    system = platform.system().lower()
-    if system == "darwin":
-        os_id = "macos"
-    elif system == "windows":
-        os_id = "windows"
-    else:
-        os_id = "linux"
-    machine = platform.machine().lower()
-    arch = "arm64" if machine in {"arm64", "aarch64"} else "x64"
-    shell = "powershell" if os_id == "windows" else "bash"
-    return {"os": os_id, "arch": arch, "shell": shell}
-
-
-def resolve_home(env: dict[str, str] | None = None, os_id: str | None = None) -> Path:
-    values = env if env is not None else os.environ
-    if values.get("ONEAGENT_HOME"):
-        return Path(values["ONEAGENT_HOME"]).expanduser()
-    platform_id = os_id or current_platform()["os"]
-    if platform_id == "windows":
-        if values.get("USERPROFILE"):
-            return Path(values["USERPROFILE"])
-        if values.get("HOMEDRIVE") and values.get("HOMEPATH"):
-            return Path(values["HOMEDRIVE"] + values["HOMEPATH"])
-    if values.get("HOME"):
-        return Path(values["HOME"])
-    return Path.home()
diff --git a/oneagent/cli.py b/oneagent/cli.py
deleted file mode 100644
index b3d8bf3f..00000000
--- a/oneagent/cli.py
+++ /dev/null
@@ -1,206 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import getpass
-import json
-import os
-import sys
-import webbrowser
-from pathlib import Path
-
-from .catalog import PROVIDERS
-from .errors import OneAgentError
-from .installer import (
-    InstallOptions,
-    Runtime,
-    activate_agent,
-    install_many,
-    list_agent_bindings,
-    read_profile_secret,
-    redact,
-)
-from .providers import provider_home
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description="Install or configure one Agent with OneAgent")
-    parser.add_argument("--agent", default="codex", help="Agent ID; comma-separated for several")
-    parser.add_argument("--provider", default="ppio")
-    parser.add_argument("--api-base-url", default="")
-    parser.add_argument("--api-key", default="")
-    parser.add_argument("--model", default="", help="Defaults to the provider's probe model")
-    parser.add_argument("--register-url", metavar="URL", default="")
-    parser.add_argument("--channel", default="direct")
-    parser.add_argument("--install-agent", action="store_true")
-    parser.add_argument("--check-agent-only", action="store_true")
-    parser.add_argument("--skip-test", action="store_true")
-    parser.add_argument("--no-open", action="store_true")
-    parser.add_argument("--json", action="store_true", dest="json_output")
-    parser.add_argument("--locked-version", action="store_true")
-    parser.add_argument("--latest", action="store_true")
-    parser.add_argument(
-        "--registry",
-        default="",
-        help="Package registry: a mirror id (official, npmmirror) or an https:// URL. Defaults to the official registry.",
-    )
-    parser.add_argument("--home", type=Path, default=None, help=argparse.SUPPRESS)
-    return parser
-
-
-def build_agent_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="oneagent agent", description="Inspect and repoint individual Agents")
-    sub = parser.add_subparsers(dest="action", required=True)
-
-    listing = sub.add_parser("list", help="Show each Agent's provider and model")
-
-    point = sub.add_parser("set", help="Point one Agent at a provider and model")
-    point.add_argument("agent_id")
-    point.add_argument("--provider", default="ppio")
-    point.add_argument("--api-base-url", default="")
-    point.add_argument("--api-key", default="")
-    point.add_argument("--model", default="", help="Defaults to a model the provider lists")
-    point.add_argument("--profile", default="", help="Reuse the key saved for this profile template")
-
-    for target in (listing, point):
-        target.add_argument("--json", action="store_true", dest="json_output")
-        target.add_argument("--home", type=Path, default=None, help=argparse.SUPPRESS)
-    return parser
-
-
-def _registration_url(args: argparse.Namespace) -> str:
-    if args.register_url:
-        return args.register_url
-    if os.environ.get("ONEAGENT_REGISTER_URL"):
-        return os.environ["ONEAGENT_REGISTER_URL"]
-    if args.provider in PROVIDERS:
-        return provider_home(args.provider)
-    return PROVIDERS["ppio"]["home"]
-
-
-def _resolve_api_key(args: argparse.Namespace) -> str:
-    if args.check_agent_only:
-        return ""
-    key = os.environ.get("ONEAGENT_API_KEY") or args.api_key
-    if key:
-        return key
-    if not sys.stdin.isatty():
-        raise OneAgentError(
-            "INVALID_REQUEST",
-            "API key is required; set ONEAGENT_API_KEY or pass --api-key (pasting interactively needs a TTY)",
-        )
-    register_url = _registration_url(args)
-    if not args.no_open:
-        webbrowser.open(register_url)
-    print(f"Create or copy an API key from: {register_url}", file=sys.stderr)
-    return getpass.getpass("Paste API key: ")
-
-
-def _run_agent_command(argv: list[str]) -> int:
-    args = build_agent_parser().parse_args(argv)
-    runtime = Runtime.create(home=args.home)
-    try:
-        if args.action == "list":
-            bindings = list_agent_bindings(runtime)
-            if args.json_output:
-                print(json.dumps({"ok": True, "agents": bindings}, ensure_ascii=False))
-            elif not bindings:
-                print("[oneagent] no Agent has been configured yet")
-            else:
-                for agent_id, binding in bindings.items():
-                    print(f"{agent_id:14} {binding['provider']:10} {binding['model']}")
-            return 0
-
-        api_key = args.api_key or os.environ.get("ONEAGENT_API_KEY", "")
-        if not api_key and args.profile:
-            api_key = read_profile_secret(runtime, args.profile)
-        result = activate_agent(
-            runtime,
-            args.agent_id,
-            provider=args.provider,
-            api_base_url=args.api_base_url,
-            api_key=api_key,
-            model=args.model,
-        )
-        if args.json_output:
-            print(json.dumps(result, ensure_ascii=False))
-        else:
-            print(f"[oneagent] {result['agent']} -> {result['provider']} / {result['model']}")
-            print(f"[oneagent] {result['restart']}")
-            print(f"[oneagent] next: {result['next']}")
-        return 0
-    except OneAgentError as exc:
-        if args.json_output:
-            print(json.dumps(exc.to_dict(), ensure_ascii=False))
-        else:
-            print(f"[oneagent] error: {exc.message}", file=sys.stderr)
-        return exc.exit_code
-
-
-def run(argv: list[str] | None = None) -> int:
-    raw = list(sys.argv[1:] if argv is None else argv)
-    # "agent" is a subcommand; every other invocation keeps the original flat
-    # flag form so existing scripts and the installers do not have to change.
-    if raw and raw[0] == "agent":
-        return _run_agent_command(raw[1:])
-    parser = build_parser()
-    args = parser.parse_args(argv)
-    api_key = ""
-    try:
-        if args.locked_version and args.latest:
-            raise OneAgentError("INVALID_REQUEST", "--locked-version and --latest cannot be used together")
-        agent_ids = [part.strip() for part in args.agent.split(",") if part.strip()]
-        api_key = _resolve_api_key(args)
-        result = install_many(
-            InstallOptions(
-                agents=agent_ids,
-                provider=args.provider,
-                api_base_url=args.api_base_url,
-                api_key=api_key,
-                model=args.model,
-                configure=not args.check_agent_only,
-                install_agent=args.install_agent,
-                check_agent_only=args.check_agent_only,
-                skip_test=args.skip_test,
-                locked_version=args.locked_version,
-                latest=args.latest,
-                registry=args.registry,
-                channel=args.channel,
-                home=args.home,
-            ),
-            Runtime.create(home=args.home),
-        )
-        if args.json_output:
-            print(json.dumps(result, ensure_ascii=False))
-        else:
-            if result["log"]:
-                print(result["log"])
-            if result["next"]:
-                for line in result["next"].splitlines():
-                    print(f"[oneagent] next: {line}")
-        return int(result["code"] if not result["ok"] else 0)
-    except OneAgentError as exc:
-        payload = exc.to_dict()
-        if args.json_output:
-            print(json.dumps(payload, ensure_ascii=False))
-        else:
-            print(f"[oneagent] error: {redact(exc.message, [api_key])}", file=sys.stderr)
-        return exc.exit_code
-    except KeyboardInterrupt:
-        return 130
-    except Exception as exc:
-        error = OneAgentError("INTERNAL_ERROR", "Unexpected OneAgent failure")
-        if args.json_output:
-            print(json.dumps(error.to_dict(), ensure_ascii=False))
-        else:
-            print(f"[oneagent] error: {error.message}", file=sys.stderr)
-        if os.environ.get("ONEAGENT_DEBUG") == "1":
-            raise
-        return error.exit_code
-
-
-def main() -> None:
-    raise SystemExit(run())
-
-
-if __name__ == "__main__":
-    main()
diff --git a/oneagent/entrypoint.py b/oneagent/entrypoint.py
deleted file mode 100644
index d4becfb2..00000000
--- a/oneagent/entrypoint.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from __future__ import annotations
-
-import sys
-
-from oneagent import cli, server
-
-
-def main() -> None:
-    if len(sys.argv) > 1:
-        if sys.argv[1] == "gui":
-            del sys.argv[1]
-            server.main()
-            return
-        cli.main()
-        return
-    server.main()
-
-
-if __name__ == "__main__":
-    main()
diff --git a/oneagent/errors.py b/oneagent/errors.py
deleted file mode 100644
index bcbf868d..00000000
--- a/oneagent/errors.py
+++ /dev/null
@@ -1,44 +0,0 @@
-from __future__ import annotations
-
-
-EXIT_CODES = {
-    "INVALID_REQUEST": 2,
-    "INVALID_ORIGIN": 2,
-    "PREREQUISITE_MISSING": 3,
-    "AGENT_INSTALL_FAILED": 4,
-    "CONFIG_WRITE_FAILED": 5,
-    "API_KEY_REJECTED": 6,
-    "PROVIDER_UNREACHABLE": 6,
-    "MODELS_UNSUPPORTED": 6,
-    "PROTOCOL_UNSUPPORTED": 7,
-    "TIMEOUT": 8,
-    "INTERNAL_ERROR": 10,
-}
-
-
-class OneAgentError(Exception):
-    def __init__(
-        self,
-        code: str,
-        message: str,
-        *,
-        retryable: bool = False,
-        status: int = 400,
-        exit_code: int | None = None,
-    ) -> None:
-        super().__init__(message)
-        self.code = code
-        self.message = message
-        self.retryable = retryable
-        self.status = status
-        self.exit_code = exit_code if exit_code is not None else EXIT_CODES.get(code, 10)
-
-    def to_dict(self) -> dict[str, object]:
-        return {
-            "ok": False,
-            "error": self.message,
-            "message": self.message,
-            "status": self.status,
-            "error_code": self.code,
-            "retryable": self.retryable,
-        }
diff --git a/oneagent/installer.py b/oneagent/installer.py
deleted file mode 100644
index 7da42199..00000000
--- a/oneagent/installer.py
+++ /dev/null
@@ -1,1744 +0,0 @@
-from __future__ import annotations
-
-import getpass
-import json
-import os
-import re
-import shlex
-import shutil
-import subprocess
-import tempfile
-import tomllib
-from dataclasses import dataclass, field, replace
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any, Callable, Iterable
-from urllib.parse import urlparse
-
-from .catalog import (
-    AGENT_GROUPS,
-    OFFICIAL_NPM_REGISTRY,
-    PACKAGE_MIRRORS,
-    PROVIDERS,
-    agent_catalog,
-    current_platform,
-    fallback_probe_model,
-    public_catalog,
-    public_mirrors,
-    public_providers,
-    resolve_home,
-)
-from .errors import EXIT_CODES, OneAgentError
-from .providers import (
-    agent_protocol,
-    list_models,
-    openai_base_url,
-    protocol_label,
-    protocol_probe,
-    provider_base,
-    provider_config_base,
-    resolve_probe_model,
-)
-
-
-Runner = Callable[..., subprocess.CompletedProcess[str]]
-
-
-@dataclass
-class InstallOptions:
-    agents: list[str]
-    profile_agents: list[str] | None = None
-    provider: str = "ppio"
-    api_base_url: str = ""
-    api_key: str = ""
-    model: str = ""
-    # Claude Code can run its fast/background work on a cheaper second model;
-    # empty falls back to `model`. Only the claude-code adapter reads it.
-    small_fast_model: str = ""
-    configure: bool = True
-    install_agent: bool = False
-    check_agent_only: bool = False
-    skip_test: bool = False
-    locked_version: bool = False
-    latest: bool = False
-    channel: str = "cli"
-    home: Path | None = None
-    os_id: str | None = None
-    timeout: int = 180
-    # Empty means the official registry. A mirror is always an explicit choice:
-    # switching automatically on a network error would leave the user unable to
-    # tell where a package came from.
-    registry: str = ""
-
-
-@dataclass
-class Runtime:
-    home: Path
-    os_id: str
-    runner: Runner = subprocess.run
-    which: Callable[[str], str | None] = shutil.which
-    env: dict[str, str] = field(default_factory=lambda: os.environ.copy())
-
-    @classmethod
-    def create(
-        cls,
-        *,
-        home: Path | None = None,
-        os_id: str | None = None,
-        runner: Runner = subprocess.run,
-        which: Callable[[str], str | None] = shutil.which,
-        env: dict[str, str] | None = None,
-    ) -> "Runtime":
-        platform_id = os_id or current_platform()["os"]
-        values = env.copy() if env is not None else os.environ.copy()
-        return cls(home or resolve_home(values, platform_id), platform_id, runner, which, values)
-
-
-def redact(text: str, secrets: Iterable[str]) -> str:
-    output = text
-    for secret in secrets:
-        if secret:
-            output = output.replace(secret, "[redacted]")
-    return output
-
-
-def _timestamp() -> str:
-    return datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
-
-
-def backup_file(path: Path) -> Path | None:
-    if not path.exists():
-        return None
-    candidate = path.with_name(f"{path.name}.backup-{_timestamp()}")
-    counter = 1
-    while candidate.exists():
-        candidate = path.with_name(f"{path.name}.backup-{_timestamp()}-{counter}")
-        counter += 1
-    shutil.copy2(path, candidate)
-    return candidate
-
-
-def _run_acl(runtime: Runtime, path: Path, *, directory: bool) -> None:
-    icacls = runtime.which("icacls")
-    if not icacls:
-        raise OneAgentError("CONFIG_WRITE_FAILED", "Windows ACL tool icacls was not found")
-    username = runtime.env.get("USERNAME") or getpass.getuser()
-    current_grant = f"{username}:(OI)(CI)F" if directory else f"{username}:F"
-    system_grant = "*S-1-5-18:(OI)(CI)F" if directory else "*S-1-5-18:F"
-    commands = [
-        [icacls, str(path), "/reset"],
-        [icacls, str(path), "/inheritance:r", "/grant:r", current_grant, system_grant],
-    ]
-    for args in commands:
-        result = runtime.runner(
-            args,
-            text=True,
-            capture_output=True,
-            timeout=30,
-            env=runtime.env,
-        )
-        if result.returncode != 0:
-            raise OneAgentError("CONFIG_WRITE_FAILED", f"Failed to secure Windows ACL for {path}")
-
-
-def secure_path(runtime: Runtime, path: Path, *, directory: bool) -> None:
-    if runtime.os_id == "windows":
-        _run_acl(runtime, path, directory=directory)
-    else:
-        path.chmod(0o700 if directory else 0o600)
-
-
-def ensure_private_dir(runtime: Runtime, path: Path) -> None:
-    path.mkdir(parents=True, exist_ok=True)
-    secure_path(runtime, path, directory=True)
-
-
-def atomic_write(runtime: Runtime, path: Path, content: str, *, secret: bool = False) -> Path | None:
-    backup: Path | None = None
-    temporary: Path | None = None
-    try:
-        ensure_private_dir(runtime, path.parent)
-        backup = backup_file(path)
-        if backup and secret:
-            try:
-                secure_path(runtime, backup, directory=False)
-            except OneAgentError:
-                try:
-                    backup.unlink()
-                except OSError as exc:
-                    raise OneAgentError(
-                        "CONFIG_WRITE_FAILED",
-                        f"Cannot remove insecure secret backup {backup}: {exc}",
-                    ) from exc
-                raise
-        with tempfile.NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as handle:
-            handle.write(content)
-            temporary = Path(handle.name)
-        # Secure the temporary inode before publishing it. On Windows this
-        # prevents an ACL failure from replacing the user's existing file.
-        secure_path(runtime, temporary, directory=False)
-        os.replace(temporary, path)
-    except OneAgentError:
-        raise
-    except OSError as exc:
-        raise OneAgentError("CONFIG_WRITE_FAILED", f"Cannot write {path}: {exc}") from exc
-    finally:
-        if temporary and temporary.exists():
-            try:
-                temporary.unlink()
-            except OSError as exc:
-                kind = "secret " if secret else ""
-                raise OneAgentError(
-                    "CONFIG_WRITE_FAILED",
-                    f"Cannot remove temporary {kind}file {temporary}: {exc}",
-                ) from exc
-    return backup
-
-
-def _powershell_quote(value: str) -> str:
-    return "'" + value.replace("'", "''") + "'"
-
-
-_ID_PATTERN = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
-
-
-def validate_agent_id(agent_id: str) -> str:
-    """Reject an Agent ID that could not be a single path segment.
-
-    Validated here, where the path is built, so every caller inherits the
-    check: the ID names a file that holds a plaintext credential, and a
-    traversal would place that key outside the private directory.
-    """
-    if not isinstance(agent_id, str) or not _ID_PATTERN.fullmatch(agent_id):
-        raise OneAgentError("INVALID_REQUEST", f"Invalid Agent ID: {agent_id!r}")
-    return agent_id
-
-
-def _config_path(runtime: Runtime, meta: dict[str, Any]) -> Path | None:
-    raw = meta.get("windows_config_path") if runtime.os_id == "windows" else meta.get("config_path")
-    if not raw:
-        raw = meta.get("config_path")
-    return runtime.home / raw if raw else None
-
-
-def _env_path(runtime: Runtime) -> Path:
-    return runtime.home / ".oneagent" / ("env.ps1" if runtime.os_id == "windows" else "env")
-
-
-def agent_env_var(agent_id: str, suffix: str = "API_KEY") -> str:
-    """Environment variable an Agent reads its credential from.
-
-    Each Agent gets its own name so three Agents that all speak
-    OpenAI-compatible can point at different providers in the same shell. A
-    single shared ONEAGENT_API_KEY made that impossible: whichever env file
-    was sourced last won.
-    """
-    stem = re.sub(r"[^A-Za-z0-9]+", "_", agent_id).strip("_").upper()
-    return f"ONEAGENT_{suffix}_{stem}"
-
-
-def needs_env_file(meta: dict[str, Any]) -> bool:
-    """Whether this Agent's credential travels through an env file.
-
-    Read from the manifest rather than a set of ids written here: the set had
-    left Claude Code out while it was the one Agent that could not authenticate
-    without one, and nothing in the code said which Agents were meant to be in
-    it or why.
-    """
-    return str(meta.get("credential_delivery", "")) in {"oneagent_env", "native_env"}
-
-
-def agent_env_path(runtime: Runtime, agent_id: str) -> Path:
-    name = validate_agent_id(agent_id)
-    suffix = "env.ps1" if runtime.os_id == "windows" else "env"
-    return runtime.home / ".oneagent" / "agents" / f"{name}.{suffix}"
-
-
-def _env_assignments(runtime: Runtime, values: dict[str, str]) -> str:
-    if runtime.os_id == "windows":
-        return "".join(f"$env:{name} = {_powershell_quote(value)}\n" for name, value in values.items())
-    return "".join(f"export {name}={shlex.quote(value)}\n" for name, value in values.items())
-
-
-def _shared_env_content(runtime: Runtime, api_key: str, base_url: str) -> str:
-    return _env_assignments(
-        runtime, {"ONEAGENT_API_KEY": api_key, "ONEAGENT_API_BASE_URL": base_url}
-    )
-
-
-def write_shared_env(runtime: Runtime, api_key: str, base_url: str) -> Path:
-    """Legacy shared credential file.
-
-    Kept because configs written by earlier versions still reference
-    ONEAGENT_API_KEY; dropping it would break those Agents on upgrade. New
-    configs read their own variable via write_agent_env.
-    """
-    path = _env_path(runtime)
-    atomic_write(runtime, path, _shared_env_content(runtime, api_key, base_url), secret=True)
-    return path
-
-
-def write_agent_env(
-    runtime: Runtime,
-    agent_id: str,
-    api_key: str,
-    base_url: str,
-    *,
-    meta: dict[str, Any] | None = None,
-    model: str = "",
-    small_fast_model: str = "",
-) -> Path:
-    """Write the env file an Agent's credential reaches it through.
-
-    Two shapes, declared per Agent as credential_delivery in the lock manifest:
-
-    oneagent_env -- the config file this adapter wrote references ONEAGENT_*
-    names (Codex's env_key, OpenCode's {env:...}), so those are what the file
-    has to define.
-
-    native_env -- the Agent only reads variable names it defines itself. Claude
-    Code is the case that proves this matters: it ignores the credential in its
-    own settings.json and answers "Not logged in" until ANTHROPIC_AUTH_TOKEN is
-    in the environment. Writing only ONEAGENT_* for it produced an Agent that
-    OneAgent reported as configured and that could not authenticate.
-    """
-    path = agent_env_path(runtime, agent_id)
-    values = {
-        agent_env_var(agent_id): api_key,
-        agent_env_var(agent_id, "API_BASE_URL"): base_url,
-        # Also define the shared names so a shell that sources only this
-        # file still satisfies a config written before per-Agent variables.
-        "ONEAGENT_API_KEY": api_key,
-        "ONEAGENT_API_BASE_URL": base_url,
-    }
-    native = (meta or {}).get("env_vars") or {}
-    if native:
-        # The Agent's own names, so sourcing this file is enough to start it.
-        for field, value in (("api_key", api_key), ("base_url", base_url), ("model", model)):
-            name = native.get(field)
-            if name and value:
-                values[str(name)] = value
-        small_fast = native.get("small_fast_model")
-        if small_fast and model:
-            values[str(small_fast)] = small_fast_model or model
-    atomic_write(runtime, path, _env_assignments(runtime, values), secret=True)
-    return path
-
-
-def write_codex_config(runtime: Runtime, meta: dict[str, Any], provider_name: str, base_url: str, model: str) -> Path:
-    path = _config_path(runtime, meta)
-    assert path is not None
-    managed = (
-        'model_provider = "oneagent"\n'
-        f'model = {json.dumps(model)}\n\n'
-        "[model_providers.oneagent]\n"
-        f"name = {json.dumps(provider_name)}\n"
-        f"base_url = {json.dumps(base_url)}\n"
-        f'env_key = {json.dumps(agent_env_var("codex"))}\n'
-        'wire_api = "responses"\n'
-    )
-    existing = ""
-    if path.exists():
-        try:
-            existing = path.read_text(encoding="utf-8")
-        except OSError as exc:
-            raise OneAgentError("CONFIG_WRITE_FAILED", f"Cannot read existing TOML configuration {path}: {exc}") from exc
-    content = _merge_codex_toml(existing, managed, path)
-    atomic_write(runtime, path, content)
-    return path
-
-
-def _merge_codex_toml(existing: str, managed: str, path: Path) -> str:
-    if not existing.strip():
-        return managed
-    try:
-        parsed = tomllib.loads(existing)
-    except tomllib.TOMLDecodeError as exc:
-        raise OneAgentError("CONFIG_WRITE_FAILED", f"Existing TOML configuration is invalid: {path}: {exc}") from exc
-
-    top_level_kept: list[str] = []
-    table_kept: list[str] = []
-    removed_top_level: set[str] = set()
-    managed_section_found = False
-    in_table = False
-    skip_managed_section = False
-    top_level_key = re.compile(r"^\s*(model_provider|model)\s*=")
-    managed_section = re.compile(r"^\[model_providers\.oneagent(?:\..+)?\]$")
-
-    for line in existing.splitlines():
-        stripped = line.strip()
-        if stripped.startswith("["):
-            header = re.sub(r"\s+", "", stripped.split("#", 1)[0])
-            in_table = True
-            skip_managed_section = bool(managed_section.fullmatch(header))
-            if skip_managed_section:
-                managed_section_found = True
-                continue
-        if skip_managed_section:
-            continue
-        if not in_table:
-            match = top_level_key.match(line)
-            if match:
-                removed_top_level.add(match.group(1))
-                continue
-        (table_kept if in_table else top_level_kept).append(line)
-
-    provider_tables = parsed.get("model_providers")
-    if isinstance(provider_tables, dict) and "oneagent" in provider_tables and not managed_section_found:
-        raise OneAgentError("CONFIG_WRITE_FAILED", f"Unsupported OneAgent TOML table syntax in {path}")
-    for key in ("model_provider", "model"):
-        if key in parsed and key not in removed_top_level:
-            raise OneAgentError("CONFIG_WRITE_FAILED", f"Unsupported TOML key syntax for {key} in {path}")
-
-    sections = ["\n".join(top_level_kept).strip(), managed.rstrip(), "\n".join(table_kept).strip()]
-    merged = "\n\n".join(section for section in sections if section) + "\n"
-    try:
-        tomllib.loads(merged)
-    except tomllib.TOMLDecodeError as exc:
-        raise OneAgentError("CONFIG_WRITE_FAILED", f"Cannot merge TOML configuration {path}: {exc}") from exc
-    return merged
-
-
-def _load_json(path: Path) -> dict[str, Any]:
-    if not path.exists():
-        return {}
-    text = path.read_text(encoding="utf-8")
-    if not text.strip():
-        return {}
-    try:
-        value = json.loads(text)
-    except json.JSONDecodeError as exc:
-        # OpenCode and Kilo use .jsonc, where comments are valid. OneAgent
-        # rewrites these files with json.dumps, which would drop the comments,
-        # so refusing is right -- but reporting a valid JSONC file as invalid
-        # JSON leaves the user with no idea what to change.
-        if path.suffix == ".jsonc" and re.search(r"(?:^|\s)(?://|/\*)", text):
-            raise OneAgentError(
-                "CONFIG_WRITE_FAILED",
-                f"{path} contains JSONC comments, which OneAgent cannot preserve when it rewrites the file. "
-                "Remove the comments, or configure this Agent manually and leave the file untouched.",
-            ) from exc
-        raise OneAgentError("CONFIG_WRITE_FAILED", f"Existing JSON configuration is invalid: {path}: {exc}") from exc
-    if not isinstance(value, dict):
-        raise OneAgentError("CONFIG_WRITE_FAILED", f"Existing JSON configuration must contain an object: {path}")
-    return value
-
-
-def write_claude_config(
-    runtime: Runtime,
-    meta: dict[str, Any],
-    base_url: str,
-    api_key: str,
-    model: str,
-    small_fast_model: str = "",
-) -> Path:
-    path = _config_path(runtime, meta)
-    assert path is not None
-    data = _load_json(path)
-    env = data.setdefault("env", {})
-    if not isinstance(env, dict):
-        raise OneAgentError("CONFIG_WRITE_FAILED", f"Existing Claude Code env configuration must contain an object: {path}")
-    env["ANTHROPIC_BASE_URL"] = base_url
-    env["ANTHROPIC_AUTH_TOKEN"] = api_key
-    env["ANTHROPIC_MODEL"] = model
-    # Claude Code drives its fast/background work from a second model. A user may
-    # point it at something cheaper; left empty it follows the main model.
-    env["ANTHROPIC_SMALL_FAST_MODEL"] = small_fast_model or model
-    atomic_write(runtime, path, json.dumps(data, ensure_ascii=False, indent=2) + "\n", secret=True)
-    return path
-
-
-def write_openai_compatible_config(
-    runtime: Runtime,
-    meta: dict[str, Any],
-    provider_name: str,
-    base_url: str,
-    model: str,
-    schema: str,
-    agent_id: str = "opencode",
-) -> Path:
-    path = _config_path(runtime, meta)
-    assert path is not None
-    data = _load_json(path)
-    data["$schema"] = schema
-    providers = data.setdefault("provider", {})
-    if not isinstance(providers, dict):
-        raise OneAgentError("CONFIG_WRITE_FAILED", f"Existing provider configuration must contain an object: {path}")
-    providers["oneagent"] = {
-        "npm": "@ai-sdk/openai-compatible",
-        "name": provider_name,
-        "options": {
-            "baseURL": openai_base_url(base_url),
-            "apiKey": "{env:" + agent_env_var(agent_id) + "}",
-        },
-        "models": {model: {"name": model}},
-    }
-    data["model"] = f"oneagent/{model}"
-    atomic_write(runtime, path, json.dumps(data, ensure_ascii=False, indent=2) + "\n")
-    return path
-
-
-def write_aider_config(runtime: Runtime, meta: dict[str, Any], base_url: str, api_key: str) -> Path:
-    path = _config_path(runtime, meta)
-    assert path is not None
-    api_base = openai_base_url(base_url)
-    if runtime.os_id == "windows":
-        content = (
-            f"$env:OPENAI_API_BASE = {_powershell_quote(api_base)}\n"
-            f"$env:OPENAI_API_KEY = {_powershell_quote(api_key)}\n"
-        )
-    else:
-        content = f"export OPENAI_API_BASE={shlex.quote(api_base)}\nexport OPENAI_API_KEY={shlex.quote(api_key)}\n"
-    atomic_write(runtime, path, content, secret=True)
-    return path
-
-
-def _version_from_output(text: str) -> str | None:
-    match = re.search(r"(?<!\d)(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)", text)
-    return match.group(1) if match else None
-
-
-def installed_version(runtime: Runtime, meta: dict[str, Any]) -> str | None:
-    command = meta.get("command")
-    executable = runtime.which(command) if command else None
-    if not executable:
-        return None
-    try:
-        result = runtime.runner(
-            [executable, *meta.get("version_args", ["--version"])],
-            text=True,
-            capture_output=True,
-            timeout=30,
-            env=runtime.env,
-        )
-    except (OSError, subprocess.TimeoutExpired):
-        return None
-    return _version_from_output((result.stdout or "") + "\n" + (result.stderr or ""))
-
-
-def _python_312_for_uv(runtime: Runtime) -> str:
-    direct = runtime.which("python3.12")
-    if direct:
-        return direct
-    for command in ("python3", "python"):
-        executable = runtime.which(command)
-        if not executable:
-            continue
-        try:
-            result = runtime.runner(
-                [executable, "--version"],
-                text=True,
-                capture_output=True,
-                timeout=30,
-                env=runtime.env,
-            )
-        except (OSError, subprocess.TimeoutExpired):
-            continue
-        version = _version_from_output((result.stdout or "") + "\n" + (result.stderr or ""))
-        if result.returncode == 0 and version and version.startswith("3.12."):
-            return executable
-    if runtime.os_id == "windows":
-        launcher = runtime.which("py")
-        if launcher:
-            try:
-                result = runtime.runner(
-                    [launcher, "-3.12", "--version"],
-                    text=True,
-                    capture_output=True,
-                    timeout=30,
-                    env=runtime.env,
-                )
-            except (OSError, subprocess.TimeoutExpired):
-                result = None
-            if result and result.returncode == 0:
-                return "3.12"
-    raise OneAgentError(
-        "PREREQUISITE_MISSING",
-        "An existing Python 3.12 installation is required for Aider; OneAgent will not download Python automatically",
-    )
-
-
-def _installer_failure_detail(runtime: Runtime, result: subprocess.CompletedProcess[str]) -> str:
-    text = (result.stderr or "") + "\n" + (result.stdout or "")
-    secrets = [
-        value
-        for key, value in runtime.env.items()
-        if value and any(marker in key.upper() for marker in ("KEY", "TOKEN", "SECRET", "PASSWORD"))
-    ]
-    text = redact(text, secrets)
-    text = re.sub(r"\x1b\[[0-9;]*m", "", text)
-    lines = [line.strip() for line in text.splitlines() if line.strip()]
-    return " | ".join(lines[-3:])[:600]
-
-
-def _require_prerequisites(runtime: Runtime, meta: dict[str, Any]) -> None:
-    package = meta.get("package") or {}
-    manager = package.get("manager")
-    if manager == "npm" and not runtime.which("npm"):
-        raise OneAgentError("PREREQUISITE_MISSING", f"npm is required to install {meta['name']}")
-    if manager == "uv":
-        if not runtime.which("uv"):
-            raise OneAgentError("PREREQUISITE_MISSING", "uv is required to install Aider")
-        _python_312_for_uv(runtime)
-    if runtime.os_id == "windows":
-        # Declared per Agent in the lock manifest (windows_prerequisites), so a
-        # new Agent's Windows requirement is added there rather than here.
-        for prerequisite in meta.get("windows_prerequisites", []):
-            if not runtime.which(str(prerequisite)):
-                raise OneAgentError(
-                    "PREREQUISITE_MISSING",
-                    f"{prerequisite} is required for {meta['name']} on Windows",
-                )
-
-
-def resolve_registry(value: str) -> str:
-    """Resolve a mirror id or explicit URL to a registry address.
-
-    HTTPS only, and credentials are refused: a registry URL ends up in the
-    installer environment and in the install log, so a token embedded in it
-    would leak into both. validate_base_url is not reused because it permits
-    http:// -- acceptable for a Provider endpoint the user names, not for the
-    address a package is fetched from.
-    """
-    if not value:
-        return OFFICIAL_NPM_REGISTRY
-    known = PACKAGE_MIRRORS.get(value)
-    if known:
-        return str(known["registry"])
-    if any(ord(char) < 32 or ord(char) == 127 for char in value):
-        raise OneAgentError("INVALID_REQUEST", "Registry URL contains control characters")
-    parsed = urlparse(value)
-    if parsed.scheme != "https" or not parsed.netloc:
-        raise OneAgentError("INVALID_REQUEST", "Registry URL must start with https://")
-    if parsed.username or parsed.password:
-        raise OneAgentError("INVALID_REQUEST", "Registry URL must not contain credentials")
-    return value if value.endswith("/") else f"{value}/"
-
-
-def verify_npm_integrity(
-    runtime: Runtime, npm: str, spec: str, expected: str, registry: str, timeout: int
-) -> None:
-    """Check the registry's integrity for a pinned spec against the manifest.
-
-    The manifest records a sha512 for every npm package but nothing ever read
-    it, so the version was pinned and the bytes were not. That gap only becomes
-    exploitable once a mirror is allowed: npm verifies a download against the
-    integrity the registry itself served, which secures the transfer but takes
-    the registry's word for what the package is. Comparing that value with the
-    manifest closes the loop -- npm proves the bytes match what the registry
-    declared, and this proves the declaration matches the official release.
-    """
-    if not expected:
-        return
-    try:
-        result = runtime.runner(
-            [npm, "view", spec, "dist.integrity", f"--registry={registry}"],
-            text=True,
-            capture_output=True,
-            timeout=timeout,
-            env=runtime.env,
-        )
-    except subprocess.TimeoutExpired as exc:
-        raise OneAgentError(
-            "AGENT_INSTALL_FAILED", f"Timed out reading the checksum for {spec}", retryable=True
-        ) from exc
-    except OSError as exc:
-        raise OneAgentError("AGENT_INSTALL_FAILED", f"Cannot read the checksum for {spec}: {exc}") from exc
-    if result.returncode != 0:
-        raise OneAgentError(
-            "AGENT_INSTALL_FAILED",
-            f"{spec} is not available on {registry}",
-            retryable=True,
-        )
-    reported = (result.stdout or "").strip()
-    if reported != expected:
-        # Fail closed and name both values: a mismatch means the registry is
-        # serving something other than the locked release, which is exactly the
-        # case a mirror has to be held to.
-        raise OneAgentError(
-            "AGENT_INSTALL_FAILED",
-            f"Checksum mismatch for {spec} on {registry}: manifest expects {expected}, registry reports {reported or '(none)'}",
-        )
-
-
-def install_locked_agent(
-    runtime: Runtime,
-    agent_id: str,
-    meta: dict[str, Any],
-    *,
-    enforce_locked: bool,
-    latest: bool,
-    timeout: int,
-    registry: str = "",
-) -> dict[str, object]:
-    command = meta.get("command")
-    executable = runtime.which(command) if command else None
-    package = meta.get("package") or {}
-    locked = package.get("version")
-    current = installed_version(runtime, meta) if executable else None
-    if executable and not enforce_locked:
-        return {"installed": False, "version": current, "lockedVersion": locked}
-    if executable and enforce_locked and current == locked:
-        return {"installed": False, "version": current, "lockedVersion": locked}
-    _require_prerequisites(runtime, meta)
-    manager = package.get("manager")
-    package_name = package.get("name")
-    resolved_registry = resolve_registry(registry)
-    env = runtime.env
-    if manager == "npm":
-        npm = runtime.which("npm")
-        assert npm is not None
-        spec = package_name if latest else f"{package_name}@{locked}"
-        if resolved_registry != OFFICIAL_NPM_REGISTRY:
-            # npm reads the registry from its environment, so no argument has to
-            # be threaded through the install command itself.
-            env = {**env, "npm_config_registry": resolved_registry}
-        if not latest:
-            # Only meaningful for a pinned spec: the manifest's checksum
-            # describes the locked version, not whatever floats at the tag.
-            verify_npm_integrity(
-                runtime, npm, spec, str(package.get("integrity", "")), resolved_registry, timeout
-            )
-        args = [npm, "install", "-g", spec]
-    elif manager == "uv":
-        uv = runtime.which("uv")
-        assert uv is not None
-        python = _python_312_for_uv(runtime)
-        spec = package_name if latest else f"{package_name}=={locked}"
-        args = [
-            uv,
-            "tool",
-            "install",
-            "--force",
-            "--python",
-            python,
-            "--no-python-downloads",
-            spec,
-        ]
-    else:
-        raise OneAgentError("PREREQUISITE_MISSING", f"No allowlisted package manager for {meta['name']}")
-    try:
-        result = runtime.runner(args, text=True, capture_output=True, timeout=timeout, env=env)
-    except subprocess.TimeoutExpired as exc:
-        raise OneAgentError("TIMEOUT", f"Installing {meta['name']} timed out", retryable=True) from exc
-    except OSError as exc:
-        raise OneAgentError("AGENT_INSTALL_FAILED", f"Cannot start installer for {meta['name']}: {exc}") from exc
-    if result.returncode != 0:
-        detail = _installer_failure_detail(runtime, result)
-        message = f"Installing {meta['name']} failed with exit code {result.returncode}"
-        if detail:
-            message += f": {detail}"
-        raise OneAgentError(
-            "AGENT_INSTALL_FAILED",
-            message,
-            retryable=True,
-        )
-    return {
-        "installed": True,
-        "version": locked if not latest else None,
-        "lockedVersion": locked,
-        "registry": resolved_registry,
-    }
-
-
-def _next_step(runtime: Runtime, agent_id: str, model: str) -> str:
-    """The command that starts this Agent against what was just written.
-
-    Derived from the manifest -- the command name and whether a credential
-    arrives through an env file are both declared there. Spelling the commands
-    out here meant Claude Code's line said plain "claude" while its credential
-    sat in a file nothing told the user to source.
-    """
-    meta = agent_catalog().get(agent_id)
-    if not meta or meta.get("config_mode") != "auto":
-        return ""
-    # Every auto Agent has a command; test_release_policy holds the manifest to
-    # that, so this does not need a second guard here.
-    command = str(meta["command"])
-    # Each Agent sources its own file, so two Agents pointing at different
-    # providers do not overwrite each other's credential in one shell.
-    joiner = ";" if runtime.os_id == "windows" else "&&"
-    if agent_id == "aider":
-        # Aider's credential is the config the adapter writes, which is itself a
-        # shell script, and the model is a launch argument rather than a field.
-        source = (
-            '. "$HOME\\.oneagent\\aider.ps1"'
-            if runtime.os_id == "windows"
-            else "source ~/.oneagent/aider.env"
-        )
-        return f"{source} {joiner} {command} --model openai/{model}"
-    if needs_env_file(meta):
-        source = (
-            f'. "$HOME\\.oneagent\\agents\\{agent_id}.env.ps1"'
-            if runtime.os_id == "windows"
-            else f"source ~/.oneagent/agents/{agent_id}.env"
-        )
-        return f"{source} {joiner} {command}"
-    return command
-
-
-def _detected(
-    base_url: str = "", model: str = "", managed: bool = False, unreadable: str = ""
-) -> dict[str, Any]:
-    """One Agent's configuration as found on disk.
-
-    Deliberately carries no credential and no hint that one exists. Three of the
-    five config formats hold the key in plain text, so a reader that returned
-    anything about it would put it in /api/status -- and even a boolean would
-    leak whether this machine has a key configured.
-    """
-    return {
-        "baseUrl": base_url,
-        "model": model,
-        "managedByOneAgent": managed,
-        "unreadable": unreadable or None,
-    }
-
-
-def read_codex_config(text: str) -> dict[str, Any]:
-    try:
-        parsed = tomllib.loads(text)
-    except tomllib.TOMLDecodeError as exc:
-        return _detected(unreadable=f"TOML 无法解析：{exc}")
-    providers = parsed.get("model_providers")
-    providers = providers if isinstance(providers, dict) else {}
-    selected = parsed.get("model_provider")
-    # Follow the provider the file actually selects, which is not necessarily
-    # ours: reading [model_providers.oneagent] unconditionally would report a
-    # configuration the Agent is not using.
-    table = providers.get(selected) if isinstance(selected, str) else None
-    base_url = ""
-    if isinstance(table, dict) and isinstance(table.get("base_url"), str):
-        base_url = str(table["base_url"])
-    model = parsed.get("model")
-    return _detected(
-        base_url=base_url,
-        model=str(model) if isinstance(model, str) else "",
-        managed="oneagent" in providers,
-    )
-
-
-def read_claude_config(text: str) -> dict[str, Any]:
-    try:
-        parsed = json.loads(text)
-    except json.JSONDecodeError as exc:
-        return _detected(unreadable=f"JSON 无法解析：{exc}")
-    if not isinstance(parsed, dict):
-        return _detected(unreadable="配置的顶层不是对象")
-    env = parsed.get("env")
-    env = env if isinstance(env, dict) else {}
-    declared = (agent_catalog().get("claude-code") or {}).get("env_vars") or {}
-    base_url = env.get(str(declared.get("base_url", "ANTHROPIC_BASE_URL")))
-    model = env.get(str(declared.get("model", "ANTHROPIC_MODEL")))
-    # Managed means every variable the adapter writes is present; a file holding
-    # only a base URL was configured by someone else.
-    managed = bool(declared) and all(env.get(str(name)) for name in declared.values())
-    return _detected(
-        base_url=str(base_url) if isinstance(base_url, str) else "",
-        model=str(model) if isinstance(model, str) else "",
-        managed=managed,
-    )
-
-
-def read_openai_compatible_config(text: str) -> dict[str, Any]:
-    try:
-        parsed = json.loads(text)
-    except json.JSONDecodeError as exc:
-        # A .jsonc file with comments is valid to its Agent and invalid here.
-        # Say which it is rather than reporting broken JSON.
-        if re.search(r"(?:^|\s)(?://|/\*)", text):
-            return _detected(unreadable="包含 JSONC 注释，OneAgent 不解析")
-        return _detected(unreadable=f"JSON 无法解析：{exc}")
-    if not isinstance(parsed, dict):
-        return _detected(unreadable="配置的顶层不是对象")
-    providers = parsed.get("provider")
-    providers = providers if isinstance(providers, dict) else {}
-    model = parsed.get("model")
-    model = str(model) if isinstance(model, str) else ""
-    # model is "<provider>/<model>"; the provider half names which table below
-    # holds the endpoint, so it selects rather than decorates.
-    selected, _, bare_model = model.partition("/")
-    table = providers.get(selected) if selected else None
-    base_url = ""
-    if isinstance(table, dict):
-        options = table.get("options")
-        if isinstance(options, dict) and isinstance(options.get("baseURL"), str):
-            base_url = str(options["baseURL"])
-    return _detected(
-        base_url=base_url,
-        model=bare_model or model,
-        managed="oneagent" in providers,
-    )
-
-
-def read_aider_config(text: str) -> dict[str, Any]:
-    """Parse the shell/PowerShell script the Aider adapter writes.
-
-    Parsed line by line and never executed: this file is written with the key in
-    it, and running it would both leak the credential into the environment and
-    hand arbitrary shell from a user-editable file to the interpreter.
-
-    managedByOneAgent is always False here, and that is deliberate. The other
-    four Agents keep their config where they look for it, so a OneAgent-shaped
-    marker inside it distinguishes our write from someone else's. Aider's config
-    is a script under ~/.oneagent that only exists because we created it, and its
-    whole content is the two exports -- there is no marker that a hand-written
-    equivalent would not also have. Claiming to tell them apart would be a guess.
-    """
-    base_url = ""
-    for line in text.splitlines():
-        match = re.match(
-            r"^(?:export\s+OPENAI_API_BASE=|\$env:OPENAI_API_BASE\s*=\s*)(.+)$", line.strip()
-        )
-        if match:
-            raw = match.group(1).strip()
-            if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in "'\"":
-                raw = raw[1:-1].replace("''", "'")
-            base_url = raw
-    return _detected(base_url=base_url)
-
-
-_CONFIG_READERS: dict[str, Callable[[str], dict[str, Any]]] = {
-    "codex": read_codex_config,
-    "claude-code": read_claude_config,
-    "opencode": read_openai_compatible_config,
-    "kilo-cli": read_openai_compatible_config,
-    "aider": read_aider_config,
-}
-
-
-def detect_agent_config(runtime: Runtime, meta: dict[str, Any]) -> dict[str, Any] | None:
-    """What this Agent is configured to use, read from its own config file.
-
-    Separate from the per-Agent binding OneAgent keeps: the binding is our own
-    bookkeeping and only exists for configurations we wrote. A user who
-    configured Codex by hand, or with another tool, had status report
-    configured=True with provider, model and baseUrl all null -- the file was
-    seen but never read.
-
-    Returns None when there is nothing to report, and never raises: a config
-    edited into invalid TOML used to make the whole status request fail, which
-    blanked the entire UI over one broken file.
-    """
-    if meta.get("config_mode") != "auto":
-        return None
-    reader = _CONFIG_READERS.get(str(meta.get("config_adapter")))
-    if reader is None:
-        return _detected(unreadable="没有可用的配置解析器")
-    path = _config_path(runtime, meta)
-    if path is None or not path.is_file():
-        return None
-    try:
-        text = path.read_text(encoding="utf-8", errors="replace")
-    except OSError as exc:
-        # Report the reason, not the contents.
-        return _detected(unreadable=f"无法读取：{exc.strerror or exc}")
-    if not text.strip():
-        return _detected(unreadable="配置文件为空")
-    try:
-        return reader(text)
-    except Exception:  # noqa: BLE001 - a reader must not be able to break status
-        return _detected(unreadable="配置解析失败")
-
-
-def _write_agent_config(
-    runtime: Runtime,
-    agent_id: str,
-    meta: dict[str, Any],
-    provider_name: str,
-    base_url: str,
-    api_key: str,
-    model: str,
-    small_fast_model: str = "",
-) -> Path:
-    adapter = meta.get("config_adapter")
-    if adapter == "codex":
-        return write_codex_config(runtime, meta, provider_name, base_url, model)
-    if adapter == "claude-code":
-        return write_claude_config(runtime, meta, base_url, api_key, model, small_fast_model)
-    if adapter == "opencode":
-        return write_openai_compatible_config(
-            runtime, meta, provider_name, base_url, model, "https://opencode.ai/config.json", agent_id
-        )
-    if adapter == "kilo-cli":
-        return write_openai_compatible_config(
-            runtime, meta, provider_name, base_url, model, "https://app.kilo.ai/config.json", agent_id
-        )
-    if adapter == "aider":
-        return write_aider_config(runtime, meta, base_url, api_key)
-    raise OneAgentError("INVALID_REQUEST", f"Unsupported auto-config Agent: {agent_id}")
-
-
-def profile_path(runtime: Runtime) -> Path:
-    return runtime.home / ".oneagent" / "profile.json"
-
-
-
-
-def profiles_dir(runtime: Runtime) -> Path:
-    return runtime.home / ".oneagent" / "profiles"
-
-
-def profile_store_path(runtime: Runtime, profile_id: str) -> Path:
-    return profiles_dir(runtime) / f"{validate_profile_id(profile_id)}.json"
-
-
-def secrets_path(runtime: Runtime, profile_id: str) -> Path:
-    # Validate at the point the path is built, not only at the callers: this
-    # decides where a plaintext key is written, so every future caller has to
-    # inherit the check rather than remember it.
-    suffix = "env.ps1" if runtime.os_id == "windows" else "env"
-    return runtime.home / ".oneagent" / "secrets" / f"{validate_profile_id(profile_id)}.{suffix}"
-
-
-def validate_profile_id(profile_id: str) -> str:
-    if not isinstance(profile_id, str) or not _ID_PATTERN.fullmatch(profile_id):
-        raise OneAgentError(
-            "INVALID_REQUEST",
-            "Profile ID must start with a lowercase letter or digit and use only lowercase letters, digits, '-' or '_'",
-        )
-    return profile_id
-
-
-def active_profile_id(runtime: Runtime) -> str | None:
-    path = profile_path(runtime)
-    if not path.exists():
-        return None
-    try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return None
-    if isinstance(value, dict) and value.get("schema_version") == 2 and isinstance(value.get("active"), str):
-        # Reject a pointer that is not a legal ID rather than returning it: the
-        # value reaches secrets_path, so a traversal here would build a key path
-        # outside the secrets directory.
-        try:
-            return validate_profile_id(str(value["active"]))
-        except OneAgentError:
-            return None
-    return None
-
-
-def agents_dir(runtime: Runtime) -> Path:
-    return runtime.home / ".oneagent" / "agents"
-
-
-def agent_binding_path(runtime: Runtime, agent_id: str) -> Path:
-    return agents_dir(runtime) / f"{validate_agent_id(agent_id)}.json"
-
-
-def read_agent_binding(runtime: Runtime, agent_id: str) -> tuple[dict[str, Any] | None, str | None]:
-    """What this Agent is currently pointed at, or why that cannot be read."""
-    path = agent_binding_path(runtime, agent_id)
-    if not path.exists():
-        return None, None
-    try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        return None, str(exc)
-    if not isinstance(value, dict):
-        return None, f"Agent binding for {agent_id} is corrupt"
-    if value.get("schema_version") != 1:
-        return None, f"Unsupported Agent binding schema for {agent_id}"
-    return value, None
-
-
-def write_agent_binding(
-    runtime: Runtime,
-    agent_id: str,
-    *,
-    provider: str,
-    base_url: str,
-    model: str,
-    profile_ref: str = "",
-) -> dict[str, Any]:
-    """Record an Agent's own provider and model. Never its key.
-
-    Bindings answer "what is this Agent pointed at" without reading the
-    Agent's own config file, whose shape differs per adapter. The credential
-    stays in the sibling .env file so this stays safe to read and report.
-    """
-    existing, _ = read_agent_binding(runtime, agent_id)
-    now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
-    binding = {
-        "schema_version": 1,
-        "agent_id": validate_agent_id(agent_id),
-        "provider": provider,
-        "base_url": base_url,
-        "model": model,
-        "profile_ref": profile_ref or (existing or {}).get("profile_ref") or "",
-        "created_at": (existing or {}).get("created_at") or now,
-        "updated_at": now,
-    }
-    ensure_private_dir(runtime, agents_dir(runtime))
-    atomic_write(
-        runtime,
-        agent_binding_path(runtime, agent_id),
-        json.dumps(binding, ensure_ascii=False, indent=2) + "\n",
-    )
-    return binding
-
-
-def list_agent_bindings(runtime: Runtime) -> dict[str, dict[str, Any]]:
-    directory = agents_dir(runtime)
-    if not directory.is_dir():
-        return {}
-    bindings: dict[str, dict[str, Any]] = {}
-    for path in sorted(directory.glob("*.json")):
-        try:
-            agent_id = validate_agent_id(path.stem)
-        except OneAgentError:
-            continue
-        value, error = read_agent_binding(runtime, agent_id)
-        if value and not error:
-            bindings[agent_id] = value
-    return bindings
-
-
-def _read_stored_profile(runtime: Runtime, profile_id: str) -> tuple[dict[str, Any] | None, str | None]:
-    path = profile_store_path(runtime, profile_id)
-    if not path.exists():
-        return None, f"Profile {profile_id} is missing"
-    try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        return None, str(exc)
-    if not isinstance(value, dict):
-        return None, f"Profile {profile_id} is corrupt"
-    return value, None
-
-
-def _write_profile_store(runtime: Runtime, profile_id: str, stored: dict[str, Any]) -> Path:
-    ensure_private_dir(runtime, profiles_dir(runtime))
-    path = profile_store_path(runtime, profile_id)
-    atomic_write(runtime, path, json.dumps(stored, ensure_ascii=False, indent=2) + "\n")
-    return path
-
-
-def _write_profile_pointer(runtime: Runtime, profile_id: str) -> Path:
-    pointer = {"schema_version": 2, "active": profile_id}
-    path = profile_path(runtime)
-    atomic_write(runtime, path, json.dumps(pointer, ensure_ascii=False, indent=2) + "\n")
-    return path
-
-
-def _write_profile_secret(runtime: Runtime, profile_id: str, api_key: str, base_url: str) -> None:
-    if not api_key:
-        return
-    atomic_write(runtime, secrets_path(runtime, profile_id), _shared_env_content(runtime, api_key, base_url), secret=True)
-
-
-def read_profile_secret(runtime: Runtime, profile_id: str) -> str:
-    """The key stored for a profile template, or "" when none is held.
-
-    Lets an Agent be pointed back at a saved provider without the user
-    re-pasting the key. Returns the value only to the caller that is about to
-    write a config with it; it is never put into a response.
-    """
-    path = secrets_path(runtime, profile_id)
-    if not path.exists():
-        return ""
-    try:
-        content = path.read_text(encoding="utf-8")
-    except OSError as exc:
-        raise OneAgentError("CONFIG_WRITE_FAILED", f"Cannot read stored key for profile {profile_id}: {exc}") from exc
-    pattern = (
-        r"^\$env:ONEAGENT_API_KEY\s*=\s*'(.*)'$"
-        if runtime.os_id == "windows"
-        else r"^export ONEAGENT_API_KEY=(.*)$"
-    )
-    match = re.search(pattern, content, re.MULTILINE)
-    if not match:
-        return ""
-    raw = match.group(1)
-    if runtime.os_id == "windows":
-        return raw.replace("''", "'")
-    return next(iter(shlex.split(raw)), "")
-
-
-def load_profile(runtime: Runtime) -> tuple[dict[str, Any] | None, str | None]:
-    """The active environment profile.
-
-    profile.json schema_version 2 is a pointer into the profiles/ store.
-    Legacy schema_version 1 files are migrated in place on first read --
-    atomic_write backs the original up first -- so an existing installation
-    upgrades instead of failing.
-    """
-    path = profile_path(runtime)
-    if not path.exists():
-        return None, None
-    try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        return None, str(exc)
-    if not isinstance(value, dict):
-        return None, "Unsupported environment profile schema"
-    schema = value.get("schema_version")
-    if schema == 1:
-        return _migrate_profile_v1(runtime, value)
-    if schema != 2 or not isinstance(value.get("active"), str):
-        return None, "Unsupported environment profile schema"
-    # The pointer is a file on disk, so its value is untrusted input even though
-    # we wrote it: anything that can edit profile.json could otherwise name a
-    # path outside the store and have it read back as a profile.
-    try:
-        active = validate_profile_id(str(value["active"]))
-    except OneAgentError as exc:
-        return None, exc.message
-    return _read_stored_profile(runtime, active)
-
-
-def _migrate_profile_v1(runtime: Runtime, legacy: dict[str, Any]) -> tuple[dict[str, Any] | None, str | None]:
-    profile_id = "default"
-    now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
-    stored = {
-        "schema_version": 2,
-        "id": profile_id,
-        "label": profile_id,
-        "provider": legacy.get("provider"),
-        "base_url": legacy.get("base_url"),
-        "model": legacy.get("model"),
-        "config_mode": legacy.get("config_mode") or "provider",
-        "agent_ids": legacy.get("agent_ids") or [],
-        "created_at": legacy.get("activated_at") or now,
-        "activated_at": legacy.get("activated_at") or now,
-    }
-    try:
-        _write_profile_store(runtime, profile_id, stored)
-        _write_profile_pointer(runtime, profile_id)
-    except OneAgentError as exc:
-        return None, f"Cannot migrate legacy profile: {exc.message}"
-    return stored, None
-
-
-def list_profiles(runtime: Runtime) -> list[dict[str, Any]]:
-    """Stored profiles in stable order, annotated with key presence.
-
-    Profiles never carry key material; whether a matching secret file exists
-    decides if the profile can be activated without re-pasting the key.
-    """
-    directory = profiles_dir(runtime)
-    if not directory.is_dir():
-        return []
-    profiles: list[dict[str, Any]] = []
-    for path in sorted(directory.glob("*.json")):
-        try:
-            value = json.loads(path.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError):
-            continue
-        if isinstance(value, dict) and isinstance(value.get("id"), str):
-            profiles.append({**value, "has_key": secrets_path(runtime, str(value["id"])).exists()})
-    return profiles
-
-
-def save_profile(
-    runtime: Runtime,
-    *,
-    profile_id: str,
-    label: str = "",
-    provider: str,
-    api_base_url: str = "",
-    model: str,
-    agent_ids: list[str],
-    api_key: str = "",
-) -> dict[str, Any]:
-    profile_id = validate_profile_id(profile_id)
-    base_url = provider_base(provider, api_base_url)
-    existing, _ = _read_stored_profile(runtime, profile_id)
-    now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
-    stored = {
-        "schema_version": 2,
-        "id": profile_id,
-        "label": label or (existing or {}).get("label") or profile_id,
-        "provider": provider,
-        "base_url": api_base_url or None,
-        "model": model,
-        "config_mode": "provider",
-        "agent_ids": sorted(set(agent_ids)),
-        "created_at": (existing or {}).get("created_at") or now,
-        "activated_at": (existing or {}).get("activated_at"),
-    }
-    _write_profile_store(runtime, profile_id, stored)
-    if api_key:
-        _write_profile_secret(runtime, profile_id, api_key, base_url)
-    return stored
-
-
-def write_profile(
-    runtime: Runtime,
-    *,
-    agents: list[str],
-    configure: bool,
-    provider: str,
-    base_url: str,
-    model: str,
-    api_key: str = "",
-) -> Path:
-    current, _ = load_profile(runtime)
-    merged_agents = set(agents)
-    profile_id = "default"
-    if current and isinstance(current.get("id"), str):
-        profile_id = str(current["id"])
-    if current and current.get("provider") == (provider if configure else "existing-account") and current.get("model") == (model if configure else None):
-        merged_agents.update(current.get("agent_ids") or [])
-    now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
-    stored = {
-        "schema_version": 2,
-        "id": profile_id,
-        "label": (current or {}).get("label") or profile_id,
-        "provider": provider if configure else "existing-account",
-        "base_url": base_url if configure else None,
-        "model": model if configure else None,
-        "config_mode": "provider" if configure else "existing-account",
-        "agent_ids": sorted(merged_agents),
-        "created_at": (current or {}).get("created_at") or now,
-        "activated_at": now,
-    }
-    _write_profile_store(runtime, profile_id, stored)
-    if configure:
-        _write_profile_secret(runtime, profile_id, api_key, base_url)
-    return _write_profile_pointer(runtime, profile_id)
-
-
-def _sharpen_model_diagnosis(probes: dict[str, dict[str, Any]], options: InstallOptions) -> None:
-    """Relabel probe failures that really mean "unknown model".
-
-    Endpoints refuse an unknown model with the same 404/400 shapes they use
-    for an unsupported protocol, so a bare probe verdict reads "model does
-    not support <protocol>" and sends the user hunting a protocol mismatch.
-    When model discovery succeeds and the model is absent from the list,
-    rewrite the failing verdicts to name the real problem plus a few valid
-    IDs. Discovery failing (or listing the model) leaves verdicts untouched:
-    then "wrong model" and "unreachable endpoint" are indistinguishable, and
-    blocking on a guess would lock offline users out.
-    """
-    failing = [verdict for verdict in probes.values() if not verdict["ok"]]
-    if not failing:
-        return
-    listing = list_models(
-        provider=options.provider,
-        custom_base=options.api_base_url,
-        api_key=options.api_key,
-        timeout=options.timeout,
-    )
-    models = listing.get("models") or []
-    if not listing.get("ok") or not models or options.model in models:
-        return
-    sample = ", ".join(models[:5])
-    for verdict in failing:
-        verdict["error_code"] = "MODELS_UNSUPPORTED"
-        verdict["retryable"] = False
-        verdict["message"] = (
-            f"Model {options.model!r} was not found in the endpoint's model list; "
-            f"the {protocol_label(str(verdict.get('protocol', '')))} probe refused it. "
-            f"Available models include: {sample}."
-        )
-
-
-def install_many(options: InstallOptions, runtime: Runtime | None = None) -> dict[str, Any]:
-    runtime = runtime or Runtime.create(home=options.home, os_id=options.os_id)
-    catalog = agent_catalog()
-    # Resolve the model once, here, rather than at each of the places that write
-    # it into a config or a next-step hint. An empty model reaches this far when
-    # a caller omits it entirely, and writing "" into an Agent config would
-    # produce a file that looks configured but cannot answer a request.
-    # Resolution prefers a model the endpoint lists right now; the catalog
-    # fallback only covers discovery failure. skip_test opts out of every
-    # network round trip, discovery included.
-    if not options.model:
-        if options.skip_test:
-            resolved_model = fallback_probe_model(options.provider)
-        else:
-            resolved_model = resolve_probe_model(
-                provider=options.provider,
-                api_key=options.api_key,
-                custom_base=options.api_base_url,
-                timeout=options.timeout,
-            )
-        options = replace(options, model=resolved_model)
-    if options.locked_version and options.latest:
-        raise OneAgentError("INVALID_REQUEST", "locked_version and latest cannot be enabled together")
-    if options.timeout <= 0:
-        raise OneAgentError("INVALID_REQUEST", "timeout must be greater than zero")
-    if not options.agents:
-        raise OneAgentError("INVALID_REQUEST", "At least one Agent is required")
-    profile_agents = options.profile_agents or options.agents
-    if not set(options.agents).issubset(profile_agents):
-        raise OneAgentError("INVALID_REQUEST", "profile_agents must include every requested Agent")
-    for agent_id in [*options.agents, *profile_agents]:
-        if agent_id not in catalog:
-            raise OneAgentError("INVALID_REQUEST", f"Unknown Agent: {agent_id}")
-
-    auto_agents = [agent_id for agent_id in options.agents if catalog[agent_id]["config_mode"] == "auto"]
-    base_url = ""
-    provider_name = ""
-    if options.configure and auto_agents and not options.check_agent_only:
-        if not options.api_key:
-            raise OneAgentError("INVALID_REQUEST", "API key is required")
-        base_url = provider_base(options.provider, options.api_base_url)
-        provider_name = PROVIDERS.get(options.provider, {"name": "Custom"})["name"]
-        env_agents = [agent for agent in auto_agents if needs_env_file(catalog[agent])]
-        for agent in env_agents:
-            write_agent_env(
-                runtime,
-                agent,
-                options.api_key,
-                base_url,
-                meta=catalog[agent],
-                model=options.model,
-                small_fast_model=options.small_fast_model,
-            )
-        if env_agents:
-            # Configs written by earlier versions still name ONEAGENT_API_KEY.
-            # Keep the shared file until those have been rewritten.
-            write_shared_env(runtime, options.api_key, base_url)
-
-    # Verify the model over each protocol the selected Agents actually speak,
-    # before any config is written. A model that answers Chat Completions may
-    # still reject Responses or Anthropic Messages, and writing a config for a
-    # pair the endpoint refuses only moves the failure into the Agent itself.
-    probes: dict[str, dict[str, Any]] = {}
-    if options.configure and auto_agents and not options.skip_test and not options.check_agent_only:
-        for protocol in sorted({agent_protocol(str(catalog[agent]["config_adapter"])) for agent in auto_agents}):
-            probes[protocol] = protocol_probe(
-                protocol=protocol,
-                provider=options.provider,
-                custom_base=options.api_base_url,
-                api_key=options.api_key,
-                model=options.model,
-                timeout=options.timeout,
-            )
-        _sharpen_model_diagnosis(probes, options)
-
-    results: list[dict[str, Any]] = []
-    logs: list[str] = []
-    next_steps: list[str] = []
-    successful: list[str] = []
-    first_exit_code = 0
-
-    for agent_id in options.agents:
-        meta = catalog[agent_id]
-        if runtime.os_id not in meta.get("platforms", []):
-            error = OneAgentError("PREREQUISITE_MISSING", f"{meta['name']} is not supported on {runtime.os_id}")
-            results.append({"agent": agent_id, "status": "failed", "code": error.exit_code, "error_code": error.code, "message": error.message, "retryable": False})
-            first_exit_code = first_exit_code or error.exit_code
-            continue
-        if meta["config_mode"] == "guide":
-            results.append({"agent": agent_id, "status": "guide-only", "message": meta["guide"], "retryable": False})
-            logs.append(f"## {agent_id}\nGuide only. {meta['guide']}")
-            next_steps.append(meta["guide"])
-            successful.append(agent_id)
-            continue
-        try:
-            install_info = {"installed": False, "version": installed_version(runtime, meta), "lockedVersion": (meta.get("package") or {}).get("version")}
-            if options.install_agent:
-                install_info = install_locked_agent(
-                    runtime,
-                    agent_id,
-                    meta,
-                    enforce_locked=options.locked_version,
-                    latest=options.latest,
-                    timeout=options.timeout,
-                    registry=options.registry,
-                )
-                if install_info.get("registry"):
-                    # Recorded so the user can tell afterwards which registry a
-                    # package actually came from.
-                    logs.append(f"## {agent_id}\nregistry: {install_info['registry']}")
-            elif meta.get("command") and not runtime.which(meta["command"]):
-                package = meta.get("package") or {}
-                manager = package.get("manager")
-                if manager == "npm":
-                    package_spec = f"{package.get('name')}@{package.get('version')}"
-                    install_command = f"npm install -g {package_spec}"
-                elif manager == "uv":
-                    package_spec = f"{package.get('name')}=={package.get('version')}"
-                    install_command = (
-                        f"uv tool install --force --python python3.12 --no-python-downloads {package_spec}"
-                    )
-                else:
-                    install_command = f"Unsupported package manager: {manager or 'missing'}"
-                logs.append(f"## {agent_id}\nofficial install: {install_command}")
-            if options.check_agent_only:
-                command_present = bool(meta.get("command") and runtime.which(meta["command"])) or bool(install_info["installed"])
-                status = "installed" if command_present else "skipped"
-                results.append({"agent": agent_id, "status": status, **install_info, "retryable": False})
-                logs.append(f"## {agent_id}\nAgent check complete.")
-                successful.append(agent_id)
-                continue
-            config_path = None
-            if options.configure:
-                adapter = str(meta.get("config_adapter") or "")
-                verdict = probes.get(agent_protocol(adapter))
-                if verdict is not None and not verdict["ok"]:
-                    raise OneAgentError(
-                        str(verdict["error_code"] or "PROVIDER_UNREACHABLE"),
-                        f"{meta['name']}: {verdict['message']}",
-                        retryable=bool(verdict["retryable"]),
-                    )
-                config_base_url = provider_config_base(
-                    options.provider,
-                    options.api_base_url,
-                    agent_protocol(adapter),
-                )
-                config_path = _write_agent_config(
-                    runtime,
-                    agent_id,
-                    meta,
-                    provider_name,
-                    config_base_url,
-                    options.api_key,
-                    options.model,
-                    options.small_fast_model,
-                )
-                # Record the binding only after the config write succeeded, so a
-                # failed write never leaves a binding claiming a state the
-                # Agent's own config does not have.
-                write_agent_binding(
-                    runtime,
-                    agent_id,
-                    provider=options.provider,
-                    base_url=config_base_url,
-                    model=options.model,
-                )
-            results.append(
-                {
-                    "agent": agent_id,
-                    "status": "configured" if options.configure else "skipped",
-                    "config": str(config_path) if config_path else "",
-                    **install_info,
-                    "retryable": False,
-                }
-            )
-            logs.append(f"## {agent_id}\n{'Configured' if options.configure else 'Model configuration skipped'}.")
-            next_step = _next_step(runtime, agent_id, options.model)
-            if next_step:
-                next_steps.append(next_step)
-            successful.append(agent_id)
-        except OneAgentError as exc:
-            first_exit_code = first_exit_code or exc.exit_code
-            results.append(
-                {
-                    "agent": agent_id,
-                    "status": "failed",
-                    "code": exc.exit_code,
-                    "error_code": exc.code,
-                    "message": exc.message,
-                    "retryable": exc.retryable,
-                }
-            )
-            logs.append(f"## {agent_id}\n{exc.message}")
-
-    # Surface the failing protocol first: with several Agents selected the GUI
-    # shows one probe, and the actionable one is the protocol that refused.
-    probe_result = None
-    for verdict in probes.values():
-        if probe_result is None or (not verdict["ok"] and probe_result["ok"]):
-            probe_result = verdict
-    for protocol, verdict in sorted(probes.items()):
-        if not verdict["ok"]:
-            first_exit_code = first_exit_code or EXIT_CODES.get(str(verdict["error_code"]), 6)
-            logs.append(f"## provider ({protocol})\n{verdict['message']}")
-
-    failed = [result for result in results if result["status"] == "failed"]
-    if not failed and (probe_result is None or probe_result["ok"]) and not options.check_agent_only:
-        write_profile(
-            runtime,
-            agents=profile_agents,
-            configure=options.configure,
-            provider=options.provider,
-            base_url=base_url,
-            model=options.model,
-            api_key=options.api_key,
-        )
-    text = redact("\n\n".join(logs), [options.api_key])
-    return {
-        "ok": not failed and (probe_result is None or bool(probe_result["ok"])),
-        "code": first_exit_code,
-        "results": results,
-        "log": text,
-        "next": "\n".join(next_steps),
-        "probe": probe_result,
-        "probes": probes,
-    }
-
-
-def public_profile_summary(item: dict[str, Any]) -> dict[str, Any]:
-    """The client-facing shape of a stored profile (camelCase, no secrets)."""
-    return {
-        "id": str(item.get("id")),
-        "label": str(item.get("label") or item.get("id")),
-        "provider": item.get("provider"),
-        "baseUrl": item.get("base_url"),
-        "model": item.get("model"),
-        "agentIds": list(item.get("agent_ids") or []),
-        "activatedAt": item.get("activated_at"),
-        "hasKey": bool(item.get("has_key")),
-    }
-
-
-def _restart_hint(agent_id: str) -> str:
-    """How the user makes a rewritten config take effect.
-
-    Agents read their config at startup, so a rewrite is invisible to an
-    already-running process. Saying "activated" without this is how a user
-    concludes the switch silently failed.
-    """
-    meta = agent_catalog().get(agent_id) or {}
-    command = str(meta.get("command", ""))
-    if not command:
-        return f"Restart {agent_id}"
-    if agent_id == "aider":
-        return f"Restart {command} in a shell that sources ~/.oneagent/aider.env"
-    if needs_env_file(meta):
-        # Restarting alone is not enough when the credential lives in a file:
-        # the new shell has to source it, or the Agent starts unauthenticated.
-        return (
-            f"Quit any running {command} process, then start it again in a shell that sources "
-            f"~/.oneagent/agents/{agent_id}.env"
-        )
-    return f"Quit any running {command} process, then start it again"
-
-
-def activate_agent(
-    runtime: Runtime,
-    agent_id: str,
-    *,
-    provider: str,
-    api_base_url: str = "",
-    api_key: str,
-    model: str,
-    small_fast_model: str = "",
-    timeout: int = 180,
-) -> dict[str, Any]:
-    """Point one Agent at a provider and model, leaving every other Agent alone.
-
-    Per-Agent credentials make this genuinely local: only this Agent's config
-    and env file change, so a failure cannot leave two Agents disagreeing and
-    there is no cross-file rollback to get right.
-    """
-    catalog = agent_catalog()
-    agent_id = validate_agent_id(agent_id)
-    meta = catalog.get(agent_id)
-    if meta is None:
-        raise OneAgentError("INVALID_REQUEST", f"Unknown Agent: {agent_id}")
-    if meta["config_mode"] != "auto":
-        raise OneAgentError("INVALID_REQUEST", f"{agent_id} is guide-only and has no managed configuration")
-    if not api_key:
-        raise OneAgentError("INVALID_REQUEST", "API key is required")
-
-    resolved_model = model or resolve_probe_model(
-        provider=provider, api_key=api_key, custom_base=api_base_url, timeout=timeout
-    )
-    provider_name = PROVIDERS.get(provider, {"name": "Custom"})["name"]
-    config_base_url = provider_config_base(provider, api_base_url, agent_protocol(str(meta["config_adapter"])))
-
-    if needs_env_file(meta):
-        write_agent_env(
-            runtime,
-            agent_id,
-            api_key,
-            provider_base(provider, api_base_url),
-            meta=meta,
-            model=resolved_model,
-            small_fast_model=small_fast_model,
-        )
-    config_path = _write_agent_config(
-        runtime, agent_id, meta, provider_name, config_base_url, api_key, resolved_model, small_fast_model
-    )
-    binding = write_agent_binding(
-        runtime, agent_id, provider=provider, base_url=config_base_url, model=resolved_model
-    )
-    return {
-        "ok": True,
-        "agent": agent_id,
-        "config": str(config_path),
-        "provider": provider,
-        "model": resolved_model,
-        "binding": binding,
-        "restart": _restart_hint(agent_id),
-        "next": _next_step(runtime, agent_id, resolved_model),
-    }
-
-
-def status_payload(runtime: Runtime | None = None) -> dict[str, Any]:
-    runtime = runtime or Runtime.create()
-    catalog = agent_catalog()
-    agents: dict[str, Any] = {}
-    paths: dict[str, str] = {"env_file": str(_env_path(runtime)), "profile": str(profile_path(runtime))}
-    capabilities: dict[str, Any] = {"canInstall": {}, "supportedAgentIds": []}
-    # Read once: the per-Agent bindings are one small directory, and reading
-    # inside the loop would re-scan it for every Agent in the catalog.
-    bindings = list_agent_bindings(runtime)
-    for agent_id, meta in catalog.items():
-        path = _config_path(runtime, meta)
-        if path:
-            paths[f"{agent_id}_config"] = str(path)
-        command = meta.get("command")
-        installed = bool(command and runtime.which(command))
-        package = meta.get("package") or {}
-        manager = package.get("manager")
-        if manager == "npm":
-            can_install = bool(runtime.which("npm"))
-        elif manager == "uv":
-            try:
-                can_install = bool(runtime.which("uv") and _python_312_for_uv(runtime))
-            except OneAgentError:
-                can_install = False
-        else:
-            can_install = False
-        if runtime.os_id == "windows":
-            for prerequisite in meta.get("windows_prerequisites", []):
-                can_install = can_install and bool(runtime.which(str(prerequisite)))
-        capabilities["canInstall"][agent_id] = can_install
-        if runtime.os_id in meta.get("platforms", []):
-            capabilities["supportedAgentIds"].append(agent_id)
-        binding = bindings.get(agent_id)
-        agents[agent_id] = {
-            "installed": installed,
-            "config": str(path) if path else "",
-            "configured": bool(path and path.exists()),
-            "guideOnly": meta["config_mode"] == "guide",
-            "version": installed_version(runtime, meta) if installed and meta["config_mode"] == "auto" else None,
-            "lockedVersion": package.get("version"),
-            "canInstall": can_install,
-            # What this Agent is pointed at, independent of every other Agent.
-            "provider": binding.get("provider") if binding else None,
-            "model": binding.get("model") if binding else None,
-            "baseUrl": binding.get("base_url") if binding else None,
-            "updatedAt": binding.get("updated_at") if binding else None,
-            # What the Agent's own config file says, alongside the binding rather
-            # than instead of it: a disagreement between the two is itself the
-            # thing worth showing, since it means the config changed outside
-            # OneAgent.
-            "detected": detect_agent_config(runtime, meta),
-        }
-    profile, profile_error = load_profile(runtime)
-    profiles = [public_profile_summary(item) for item in list_profiles(runtime)]
-    # Backups are derived from each Agent's declared config_path rather than a
-    # hand-written pair: a new auto Agent's backups appear here the moment its
-    # lock entry lands, with no second place to keep in sync.
-    backups: dict[str, bool] = {}
-    for backup_agent_id, backup_meta in catalog.items():
-        backup_path = _config_path(runtime, backup_meta)
-        if backup_path is not None:
-            backups[backup_agent_id] = bool(list(backup_path.parent.glob(f"{backup_path.name}.backup-*")))
-    oneagent_dir = runtime.home / ".oneagent"
-    backups["env"] = bool(list(oneagent_dir.glob(f"{_env_path(runtime).name}.backup-*")))
-    backups["profile"] = bool(list(oneagent_dir.glob("profile.json.backup-*")))
-    return {
-        "apiVersion": 1,
-        "platform": {**current_platform(), "os": runtime.os_id},
-        "capabilities": capabilities,
-        "agents": agents,
-        "catalog": public_catalog(),
-        "groups": AGENT_GROUPS,
-        "providers": public_providers(),
-        "mirrors": public_mirrors(),
-        "paths": paths,
-        "backups": backups,
-        "profiles": profiles,
-        "activeProfile": active_profile_id(runtime),
-        "environment": profile,
-        "environmentError": profile_error,
-    }
diff --git a/oneagent/providers.py b/oneagent/providers.py
deleted file mode 100644
index 8b6f0df1..00000000
--- a/oneagent/providers.py
+++ /dev/null
@@ -1,405 +0,0 @@
-from __future__ import annotations
-
-import json
-import re
-import socket
-from typing import Any
-from urllib.error import HTTPError, URLError
-from urllib.parse import urlparse
-from urllib.request import Request, urlopen
-
-from .catalog import (
-    PROTOCOL_ANTHROPIC,
-    PROTOCOL_OPENAI,
-    PROTOCOL_RESPONSES,
-    PROVIDERS,
-    agent_protocol,
-    fallback_probe_model,
-)
-from .errors import OneAgentError
-
-__all__ = [
-    "PROTOCOL_ANTHROPIC",
-    "PROTOCOL_OPENAI",
-    "PROTOCOL_RESPONSES",
-    "agent_protocol",
-    "anthropic_messages_url",
-    "chat_probe",
-    "list_models",
-    "openai_base_url",
-    "pick_chat_model",
-    "protocol_label",
-    "protocol_probe",
-    "provider_base",
-    "provider_config_base",
-    "provider_home",
-    "resolve_probe_model",
-    "validate_base_url",
-]
-
-
-def validate_base_url(value: str) -> str:
-    if not value:
-        raise OneAgentError("INVALID_REQUEST", "Custom base URL is required")
-    if any(ord(char) < 32 or ord(char) == 127 for char in value):
-        raise OneAgentError("INVALID_REQUEST", "Custom base URL contains control characters")
-    parsed = urlparse(value)
-    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
-        raise OneAgentError("INVALID_REQUEST", "Custom base URL must start with http:// or https://")
-    if parsed.username or parsed.password:
-        raise OneAgentError("INVALID_REQUEST", "Custom base URL must not contain credentials")
-    return value.rstrip("/")
-
-
-def provider_base(provider: str, custom_base: str = "") -> str:
-    if provider not in {*PROVIDERS, "custom"}:
-        raise OneAgentError("INVALID_REQUEST", "Provider must be ppio, novita, or custom")
-    if custom_base:
-        return validate_base_url(custom_base)
-    if provider == "custom":
-        return validate_base_url(custom_base)
-    return PROVIDERS[provider]["base_url"]
-
-
-def provider_config_base(provider: str, custom_base: str, protocol: str) -> str:
-    """The base URL a config write or probe targets for one inference protocol.
-
-    Anthropic-speaking Agents are served from a separate route on the managed
-    providers, so the decision is keyed on the protocol -- derived from the
-    Agent's adapter by callers via agent_protocol() -- rather than on an Agent
-    id. A custom base or a non-Anthropic protocol keeps the OpenAI-compatible
-    URL.
-    """
-    base_url = provider_base(provider, custom_base)
-    if protocol == PROTOCOL_ANTHROPIC and provider in PROVIDERS and not custom_base:
-        return PROVIDERS[provider]["anthropic_base_url"]
-    return base_url
-
-
-PROTOCOL_LABELS = {
-    PROTOCOL_OPENAI: "OpenAI Chat Completions",
-    PROTOCOL_ANTHROPIC: "Anthropic Messages",
-    PROTOCOL_RESPONSES: "OpenAI Responses",
-}
-
-# Endpoints answer "this model cannot serve this protocol" with several shapes:
-# 400 INVALID_REQUEST_BODY "does not support endpoint", 500 "not implemented",
-# and plain 404/405 when the route is absent. All are permanent for the pair, so
-# they must not be reported as retryable.
-_UNSUPPORTED_MARKERS = (
-    "does not support endpoint",
-    "not implemented",
-    "unsupported endpoint",
-    "unknown endpoint",
-)
-
-
-def protocol_label(protocol: str) -> str:
-    return PROTOCOL_LABELS.get(protocol, protocol)
-
-
-def provider_home(provider: str) -> str:
-    if provider not in PROVIDERS:
-        raise OneAgentError("INVALID_REQUEST", "Registration is only available for ppio or novita")
-    return PROVIDERS[provider]["home"]
-
-
-def openai_base_url(base_url: str) -> str:
-    base = base_url.rstrip("/")
-    for suffix in ("/chat/completions", "/responses", "/models"):
-        if base.endswith(suffix):
-            base = base[: -len(suffix)].rstrip("/")
-    return base if base.endswith("/v1") else base + "/v1"
-
-
-def anthropic_messages_url(base_url: str) -> str:
-    """Anthropic bases arrive in both shapes: PPIO/Novita expose
-    `.../anthropic` with no version segment, while a custom base is commonly
-    pasted already ending in `/v1`. Normalise both to exactly one `/v1/messages`."""
-    base = base_url.rstrip("/")
-    for suffix in ("/v1/messages", "/messages"):
-        if base.endswith(suffix):
-            base = base[: -len(suffix)].rstrip("/")
-            break
-    if base.endswith("/v1"):
-        return base + "/messages"
-    return base + "/v1/messages"
-
-
-def _request_error(exc: Exception, *, models: bool = False) -> dict[str, Any]:
-    if isinstance(exc, HTTPError):
-        if exc.code in {401, 403}:
-            message = f"API key was rejected ({exc.code})."
-            if models:
-                message += " Enter model ID manually."
-            return {
-                "ok": False,
-                "reachable": True,
-                "models": [] if models else None,
-                "status": exc.code,
-                "message": message,
-                "error_code": "API_KEY_REJECTED",
-                "retryable": True,
-            }
-        if models and exc.code in {404, 405}:
-            return {
-                "ok": False,
-                "reachable": True,
-                "models": [],
-                "status": exc.code,
-                "message": f"This endpoint does not expose /v1/models ({exc.code}); enter model ID manually.",
-                "error_code": "MODELS_UNSUPPORTED",
-                "retryable": False,
-            }
-        return {
-            "ok": False,
-            "reachable": True,
-            "models": [] if models else None,
-            "status": exc.code,
-            "message": f"Endpoint returned HTTP {exc.code}.",
-            "error_code": "PROVIDER_UNREACHABLE",
-            "retryable": exc.code >= 500,
-        }
-    reason = exc.reason if isinstance(exc, URLError) else str(exc)
-    code = "TIMEOUT" if isinstance(reason, (socket.timeout, TimeoutError)) or "timed out" in str(reason).lower() else "PROVIDER_UNREACHABLE"
-    return {
-        "ok": False,
-        "reachable": False,
-        "models": [] if models else None,
-        "status": 0,
-        "message": f"Cannot reach endpoint: {reason}",
-        "error_code": code,
-        "retryable": True,
-    }
-
-
-def _protocol_request(
-    protocol: str,
-    *,
-    provider: str,
-    custom_base: str,
-    api_key: str,
-    model: str,
-) -> Request:
-    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
-    if protocol == PROTOCOL_ANTHROPIC:
-        url = anthropic_messages_url(provider_config_base(provider, custom_base, protocol))
-        headers["X-Api-Key"] = api_key
-        headers["Anthropic-Version"] = "2023-06-01"
-        body: dict[str, Any] = {
-            "model": model,
-            "messages": [{"role": "user", "content": "ping"}],
-            "max_tokens": 1,
-        }
-    else:
-        v1 = openai_base_url(provider_base(provider, custom_base))
-        if protocol == PROTOCOL_RESPONSES:
-            url = v1 + "/responses"
-            # Reasoning models spend the budget before emitting text, so an
-            # over-tight cap fails for a reason unrelated to protocol support.
-            body = {"model": model, "input": "ping", "max_output_tokens": 16}
-        else:
-            url = v1 + "/chat/completions"
-            body = {
-                "model": model,
-                "messages": [{"role": "user", "content": "ping"}],
-                "max_tokens": 1,
-            }
-    return Request(url, data=json.dumps(body).encode(), method="POST", headers=headers)
-
-
-def _unsupported_protocol(code: int, body: str) -> bool:
-    if code in {404, 405, 501}:
-        return True
-    if code in {400, 422, 500}:
-        lowered = body.lower()
-        return any(marker in lowered for marker in _UNSUPPORTED_MARKERS)
-    return False
-
-
-def protocol_probe(
-    *,
-    protocol: str,
-    provider: str,
-    api_key: str,
-    model: str,
-    custom_base: str = "",
-    timeout: float = 10,
-) -> dict[str, Any]:
-    """Send one minimal request over `protocol` and report whether the model
-    actually serves it. Passing Chat Completions does not prove a model answers
-    Responses or Anthropic Messages, so each Agent must be checked separately."""
-    if not api_key:
-        raise OneAgentError("INVALID_REQUEST", "API key is required")
-    if protocol not in PROTOCOL_LABELS:
-        raise OneAgentError("INVALID_REQUEST", f"Unknown inference protocol: {protocol}")
-    request = _protocol_request(
-        protocol,
-        provider=provider,
-        custom_base=custom_base,
-        api_key=api_key,
-        model=model or fallback_probe_model(provider),
-    )
-    label = protocol_label(protocol)
-    try:
-        with urlopen(request, timeout=timeout) as response:
-            return {
-                "ok": response.status in {200, 204},
-                "reachable": True,
-                "protocol": protocol,
-                "status": response.status,
-                "message": f"{label} connection test passed.",
-                "error_code": None,
-                "retryable": False,
-            }
-    except (HTTPError, URLError, TimeoutError, socket.timeout) as exc:
-        try:
-            if isinstance(exc, HTTPError):
-                try:
-                    body = exc.read().decode(errors="replace")
-                except OSError:
-                    body = ""
-                if _unsupported_protocol(exc.code, body):
-                    return {
-                        "ok": False,
-                        "reachable": True,
-                        "protocol": protocol,
-                        "status": exc.code,
-                        "message": (
-                            f"Model {model!r} does not support {label}. "
-                            "Choose a model that serves this protocol."
-                        ),
-                        "error_code": "PROTOCOL_UNSUPPORTED",
-                        "retryable": False,
-                    }
-            result = _request_error(exc)
-            result.pop("models", None)
-            result["protocol"] = protocol
-            return result
-        finally:
-            if isinstance(exc, HTTPError):
-                exc.close()
-
-
-def chat_probe(
-    *,
-    provider: str,
-    api_key: str,
-    model: str,
-    custom_base: str = "",
-    timeout: float = 10,
-) -> dict[str, Any]:
-    return protocol_probe(
-        protocol=PROTOCOL_OPENAI,
-        provider=provider,
-        api_key=api_key,
-        model=model,
-        custom_base=custom_base,
-        timeout=timeout,
-    )
-
-
-def list_models(
-    *,
-    provider: str,
-    api_key: str,
-    custom_base: str = "",
-    timeout: float = 10,
-) -> dict[str, Any]:
-    if not api_key:
-        raise OneAgentError("INVALID_REQUEST", "API key is required")
-    base_url = provider_base(provider, custom_base)
-    request = Request(
-        openai_base_url(base_url) + "/models",
-        method="GET",
-        headers={"Authorization": f"Bearer {api_key}"},
-    )
-    try:
-        with urlopen(request, timeout=timeout) as response:
-            raw = json.loads(response.read().decode())
-    except (HTTPError, URLError, TimeoutError, socket.timeout) as exc:
-        try:
-            return _request_error(exc, models=True)
-        finally:
-            if isinstance(exc, HTTPError):
-                exc.close()
-    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
-        return {
-            "ok": False,
-            "reachable": True,
-            "models": [],
-            "status": 200,
-            "message": f"Model list response is not valid JSON: {exc}",
-            "error_code": "MODELS_UNSUPPORTED",
-            "retryable": False,
-        }
-
-    data = raw if isinstance(raw, list) else raw.get("data", []) if isinstance(raw, dict) else []
-    if not isinstance(data, list):
-        data = []
-    models: list[str] = []
-    for item in data:
-        if isinstance(item, dict) and item.get("id"):
-            models.append(str(item["id"]))
-        elif isinstance(item, str):
-            models.append(item)
-    return {
-        "ok": bool(models),
-        "reachable": True,
-        "models": models,
-        "status": 200,
-        "message": f"Found {len(models)} models." if models else "No model IDs returned; enter model ID manually.",
-        "error_code": None if models else "MODELS_UNSUPPORTED",
-        "retryable": False,
-    }
-
-
-# Model lists are provider-ordered and frequently lead with embedding, rerank
-# or vision models. Probing a protocol endpoint with one of those fails for a
-# reason unrelated to connectivity or the key, so pick the first ID that does
-# not carry an obvious non-chat marker. Markers match on separators only, so
-# an ID that merely contains a marker substring stays eligible.
-_NON_CHAT_MODEL = re.compile(
-    r"(?:^|[-_/.])(?:embed(?:ding)?s?|rerank(?:er)?|ocr|whisper|asr|tts|speech|vl|vision|image|sdx?|flux|guard(?:rail)?s?|moderation|sql)(?:[-_/.]|$)",
-    re.IGNORECASE,
-)
-
-
-def pick_chat_model(models: list[str]) -> str:
-    """Pick the first model that plausibly serves chat.
-
-    `models` must be non-empty; callers only invoke this on a successful
-    discovery. When every listed model looks non-chat the first entry is
-    returned and the probe failure explains itself.
-    """
-    for model in models:
-        if not _NON_CHAT_MODEL.search(model):
-            return model
-    return models[0]
-
-
-def resolve_probe_model(
-    *,
-    provider: str,
-    api_key: str,
-    model: str = "",
-    custom_base: str = "",
-    timeout: float = 10,
-) -> str:
-    """The model to probe with when the user has not chosen one.
-
-    Prefer a model the endpoint lists right now: hardcoded IDs go stale when
-    a provider retires a model. A user-supplied model short-circuits
-    discovery so a probe never costs an extra round trip, and an absent key
-    skips it because list_models would refuse. Discovery failing is not
-    fatal -- the catalog fallback is the narrow last resort.
-    """
-    if model:
-        return model
-    if not api_key:
-        return fallback_probe_model(provider)
-    listing = list_models(provider=provider, api_key=api_key, custom_base=custom_base, timeout=timeout)
-    models = listing.get("models") or []
-    if listing.get("ok") and models:
-        return pick_chat_model(models)
-    return fallback_probe_model(provider)
diff --git a/oneagent/server.py b/oneagent/server.py
deleted file mode 100644
index ff33702a..00000000
--- a/oneagent/server.py
+++ /dev/null
@@ -1,503 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import json
-import mimetypes
-import os
-import re
-import secrets
-import socketserver
-import sys
-import webbrowser
-from http.cookies import SimpleCookie
-from http.server import BaseHTTPRequestHandler, HTTPServer
-from pathlib import Path
-from urllib.parse import quote, unquote, urlsplit
-
-from .catalog import agent_catalog, resource_root
-from .errors import OneAgentError
-from .installer import (
-    InstallOptions,
-    Runtime,
-    activate_agent,
-    active_profile_id,
-    install_many,
-    list_profiles,
-    public_profile_summary,
-    read_profile_secret,
-    save_profile,
-    secrets_path,
-    status_payload,
-)
-from .providers import (
-    PROTOCOL_OPENAI,
-    agent_protocol,
-    resolve_probe_model,
-    list_models,
-    protocol_probe,
-    provider_home,
-)
-
-
-MAX_BODY_BYTES = 65536
-ALLOWED_MIME_PREFIXES = ("text/", "image/", "font/")
-ALLOWED_MIME_TYPES = {
-    "application/javascript",
-    "application/json",
-    "application/manifest+json",
-}
-CSP = (
-    "default-src 'self'; "
-    "script-src 'self'; "
-    "style-src 'self'; "
-    "img-src 'self' data:; "
-    "font-src 'self'; "
-    "connect-src 'self'; "
-    "object-src 'none'; "
-    "base-uri 'none'; "
-    "frame-ancestors 'none'; "
-    "form-action 'self'"
-)
-
-
-def static_root() -> Path:
-    return resource_root() / "frontend" / "dist"
-
-
-def json_response(handler: BaseHTTPRequestHandler, status: int, payload: dict[str, object]) -> None:
-    data = json.dumps(payload, ensure_ascii=False).encode()
-    handler.send_response(status)
-    handler.send_header("Content-Type", "application/json; charset=utf-8")
-    handler.send_header("Content-Length", str(len(data)))
-    handler.send_header("Cache-Control", "no-store")
-    handler.send_header("X-Content-Type-Options", "nosniff")
-    handler.send_header("Content-Security-Policy", CSP)
-    handler.end_headers()
-    handler.wfile.write(data)
-
-
-def error_response(handler: BaseHTTPRequestHandler, exc: Exception) -> None:
-    if isinstance(exc, OneAgentError):
-        json_response(handler, exc.status, exc.to_dict())
-        return
-    error = OneAgentError("INTERNAL_ERROR", "Unexpected OneAgent server failure", status=500)
-    if os.environ.get("ONEAGENT_DEBUG") == "1":
-        error.message = str(exc)
-    json_response(handler, error.status, error.to_dict())
-
-
-def read_json(handler: BaseHTTPRequestHandler) -> dict[str, object]:
-    try:
-        length = int(handler.headers.get("Content-Length", "0"))
-    except ValueError as exc:
-        raise OneAgentError("INVALID_REQUEST", "Invalid Content-Length") from exc
-    if length < 0 or length > MAX_BODY_BYTES:
-        raise OneAgentError("INVALID_REQUEST", "Request body is too large")
-    if length == 0:
-        return {}
-    try:
-        value = json.loads(handler.rfile.read(length).decode())
-    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
-        raise OneAgentError("INVALID_REQUEST", "Request body must be valid JSON") from exc
-    if not isinstance(value, dict):
-        raise OneAgentError("INVALID_REQUEST", "Request body must contain a JSON object")
-    return value
-
-
-def _allowed_origins(handler: BaseHTTPRequestHandler) -> set[str]:
-    port = handler.server.server_port
-    return {f"http://127.0.0.1:{port}", f"http://localhost:{port}"}
-
-
-def assert_session(handler: BaseHTTPRequestHandler) -> None:
-    origin = handler.headers.get("Origin")
-    if not origin or origin not in _allowed_origins(handler):
-        raise OneAgentError("INVALID_ORIGIN", "Invalid or missing Origin", status=403)
-    cookie = SimpleCookie()
-    cookie.load(handler.headers.get("Cookie", ""))
-    supplied = cookie.get("oneagent_session")
-    expected = getattr(handler.server, "session_token", "")
-    if not supplied or not secrets.compare_digest(supplied.value, expected):
-        raise OneAgentError("INVALID_ORIGIN", "Missing or invalid OneAgent session", status=403)
-
-
-def _safe_static_file(request_path: str) -> Path:
-    root = static_root().resolve()
-    raw_path = unquote(urlsplit(request_path).path)
-    if any(part == ".." for part in Path(raw_path).parts) or "\x00" in raw_path:
-        raise OneAgentError("INVALID_REQUEST", "Invalid static path", status=404)
-    relative = raw_path.lstrip("/") or "index.html"
-    candidate = (root / relative).resolve()
-    try:
-        candidate.relative_to(root)
-    except ValueError as exc:
-        raise OneAgentError("INVALID_REQUEST", "Invalid static path", status=404) from exc
-    if not candidate.is_file():
-        raise OneAgentError("INVALID_REQUEST", "Static file not found", status=404)
-    return candidate
-
-
-def _mime_type(path: Path) -> str:
-    mime, _ = mimetypes.guess_type(path.name)
-    value = mime or "application/octet-stream"
-    if not value.startswith(ALLOWED_MIME_PREFIXES) and value not in ALLOWED_MIME_TYPES:
-        raise OneAgentError("INVALID_REQUEST", "Static file type is not allowed", status=404)
-    return value
-
-
-def static_response(handler: BaseHTTPRequestHandler, request_path: str) -> None:
-    try:
-        path = _safe_static_file(request_path)
-    except OneAgentError as exc:
-        if urlsplit(request_path).path in {"/", "/index.html"}:
-            body = (
-                "<!doctype html><meta charset='utf-8'><title>OneAgent</title>"
-                "<p>OneAgent frontend build is missing. Run the frontend build before starting the GUI.</p>"
-            ).encode()
-            handler.send_response(503)
-            handler.send_header("Content-Type", "text/html; charset=utf-8")
-            handler.send_header("Content-Length", str(len(body)))
-            handler.send_header("Cache-Control", "no-store")
-            handler.send_header("Content-Security-Policy", CSP)
-            handler.send_header(
-                "Set-Cookie",
-                f"oneagent_session={handler.server.session_token}; HttpOnly; SameSite=Strict; Path=/api",
-            )
-            handler.end_headers()
-            handler.wfile.write(body)
-            return
-        raise exc
-    mime_type = _mime_type(path)
-    body = path.read_bytes()
-    handler.send_response(200)
-    handler.send_header("Content-Type", mime_type)
-    handler.send_header("Content-Length", str(len(body)))
-    handler.send_header("X-Content-Type-Options", "nosniff")
-    handler.send_header("Content-Security-Policy", CSP)
-    if path.name == "index.html":
-        handler.send_header("Cache-Control", "no-store")
-        handler.send_header(
-            "Set-Cookie",
-            f"oneagent_session={handler.server.session_token}; HttpOnly; SameSite=Strict; Path=/api",
-        )
-    elif path.parent.name == "assets" and re.search(r"[-.][A-Za-z0-9_-]{8,}[-.]", path.name):
-        handler.send_header("Cache-Control", "public, max-age=31536000, immutable")
-    else:
-        handler.send_header("Cache-Control", "no-cache")
-    handler.end_headers()
-    handler.wfile.write(body)
-
-
-def _timeout() -> float:
-    try:
-        return float(os.environ.get("ONEAGENT_HTTP_TIMEOUT", "10"))
-    except ValueError:
-        return 10
-
-
-def _runtime() -> Runtime:
-    return Runtime.create()
-
-
-def _string_field(payload: dict[str, object], name: str, default: str = "") -> str:
-    value = payload.get(name, default)
-    if not isinstance(value, str):
-        raise OneAgentError("INVALID_REQUEST", f"{name} must be a string")
-    return value
-
-
-def _bool_field(payload: dict[str, object], name: str, default: bool = False) -> bool:
-    value = payload.get(name, default)
-    if not isinstance(value, bool):
-        raise OneAgentError("INVALID_REQUEST", f"{name} must be a boolean")
-    return value
-
-
-def _agents_field(payload: dict[str, object]) -> list[str]:
-    if "agents" in payload:
-        agents = payload["agents"]
-    else:
-        agent = payload.get("agent", "codex")
-        agents = [agent]
-    if not isinstance(agents, list) or not agents or not all(isinstance(item, str) and item for item in agents):
-        raise OneAgentError("INVALID_REQUEST", "agents must be a non-empty array of Agent IDs")
-    unknown = [agent for agent in agents if agent not in agent_catalog()]
-    if unknown:
-        raise OneAgentError("INVALID_REQUEST", f"Unknown Agent: {unknown[0]}")
-    return agents
-
-
-def _optional_agents_field(payload: dict[str, object], name: str) -> list[str] | None:
-    if name not in payload or payload[name] is None:
-        return None
-    value = payload[name]
-    if not isinstance(value, list) or not value or not all(isinstance(item, str) and item for item in value):
-        raise OneAgentError("INVALID_REQUEST", f"{name} must be a non-empty array of Agent IDs")
-    unknown = [agent for agent in value if agent not in agent_catalog()]
-    if unknown:
-        raise OneAgentError("INVALID_REQUEST", f"Unknown Agent: {unknown[0]}")
-    return value
-
-
-def _timeout_field(payload: dict[str, object]) -> int:
-    value = payload.get("timeout", 180)
-    if isinstance(value, bool) or not isinstance(value, int) or value <= 0 or value > 3600:
-        raise OneAgentError("INVALID_REQUEST", "timeout must be an integer between 1 and 3600")
-    return value
-
-
-def probe_payload(payload: dict[str, object]) -> dict[str, object]:
-    provider = _string_field(payload, "provider", "ppio")
-    custom_base = _string_field(payload, "api_base_url")
-    api_key = _string_field(payload, "api_key")
-    timeout = _timeout()
-    # The wizard probes before the model step, so an empty model is the norm
-    # here; resolve a model the endpoint actually serves right now.
-    model = resolve_probe_model(
-        provider=provider,
-        custom_base=custom_base,
-        api_key=api_key,
-        model=_string_field(payload, "model"),
-        timeout=timeout,
-    )
-
-    # Test the protocols the selected Agents will really speak. Without an Agent
-    # list this stays an OpenAI-compatible check, which is all the older clients
-    # ever asked for.
-    catalog = agent_catalog()
-    agents = _optional_agents_field(payload, "agents") or []
-    protocols = sorted(
-        {
-            agent_protocol(str(catalog[agent].get("config_adapter") or ""))
-            for agent in agents
-            if catalog[agent]["config_mode"] == "auto"
-        }
-    ) or [PROTOCOL_OPENAI]
-
-    results = {
-        protocol: protocol_probe(
-            protocol=protocol,
-            provider=provider,
-            custom_base=custom_base,
-            api_key=api_key,
-            model=model,
-            timeout=timeout,
-        )
-        for protocol in protocols
-    }
-    # Report the actionable protocol: the one that refused, if any.
-    primary = next((r for r in results.values() if not r["ok"]), results[protocols[0]])
-    return {**primary, "ok": all(r["ok"] for r in results.values()), "protocols": results}
-
-
-def models_payload(payload: dict[str, object]) -> dict[str, object]:
-    return list_models(
-        provider=_string_field(payload, "provider", "ppio"),
-        custom_base=_string_field(payload, "api_base_url"),
-        api_key=_string_field(payload, "api_key"),
-        timeout=_timeout(),
-    )
-
-
-def profiles_payload(runtime: Runtime) -> dict[str, object]:
-    return {
-        "ok": True,
-        "profiles": [public_profile_summary(item) for item in list_profiles(runtime)],
-        "activeProfile": active_profile_id(runtime),
-    }
-
-
-def _slugify_profile_id(raw: str) -> str:
-    # Turn "<provider>-<model>" into a filesystem- and URL-safe profile ID.
-    slug = re.sub(r"[^a-z0-9]+", "-", raw.lower()).strip("-")[:64].strip("-")
-    return slug or "profile"
-
-
-def save_profile_payload(payload: dict[str, object]) -> dict[str, object]:
-    runtime = _runtime()
-    provider = _string_field(payload, "provider", "ppio")
-    model = _string_field(payload, "model")
-    if not model:
-        raise OneAgentError("INVALID_REQUEST", "model is required")
-    profile_id = _string_field(payload, "profile_id") or _slugify_profile_id(f"{provider}-{model}")
-    agents = _optional_agents_field(payload, "agents")
-    if agents is None:
-        raise OneAgentError("INVALID_REQUEST", "agents must be a non-empty array of Agent IDs")
-    stored = save_profile(
-        runtime,
-        profile_id=profile_id,
-        label=_string_field(payload, "label"),
-        provider=provider,
-        api_base_url=_string_field(payload, "api_base_url"),
-        model=model,
-        agent_ids=agents,
-        api_key=_string_field(payload, "api_key"),
-    )
-    summary = public_profile_summary({**stored, "has_key": secrets_path(runtime, str(stored["id"])).exists()})
-    return {"ok": True, "profile": summary}
-
-
-_AGENT_ACTIVATE_ROUTE = re.compile(r"^/api/agents/([^/]+)/activate$")
-
-
-def _agent_activate_match(path: str) -> str | None:
-    """The Agent ID in /api/agents/<id>/activate, or None for another route.
-
-    Only shape is checked here; activate_agent validates the ID itself, so an
-    unknown or malformed ID becomes a structured error rather than a 404 that
-    looks like the endpoint is missing.
-    """
-    match = _AGENT_ACTIVATE_ROUTE.match(path)
-    return unquote(match.group(1)) if match else None
-
-
-def activate_agent_payload(agent_id: str, payload: dict[str, object]) -> dict[str, object]:
-    runtime = _runtime()
-    provider = _string_field(payload, "provider", "ppio")
-    api_base_url = _string_field(payload, "api_base_url")
-    api_key = _string_field(payload, "api_key")
-    if not api_key:
-        # Reuse the key already stored for a profile so switching an Agent back
-        # to a saved provider does not require pasting it again.
-        profile_ref = _string_field(payload, "profile_id")
-        if profile_ref:
-            api_key = read_profile_secret(runtime, profile_ref)
-    return activate_agent(
-        runtime,
-        agent_id,
-        provider=provider,
-        api_base_url=api_base_url,
-        api_key=api_key,
-        model=_string_field(payload, "model"),
-        small_fast_model=_string_field(payload, "small_fast_model"),
-        timeout=_timeout(),
-    )
-
-
-def install_payload(payload: dict[str, object]) -> dict[str, object]:
-    agents = _agents_field(payload)
-    configure = _bool_field(payload, "configure", True)
-    return install_many(
-        InstallOptions(
-            agents=agents,
-            profile_agents=_optional_agents_field(payload, "profile_agents"),
-            provider=_string_field(payload, "provider", "ppio"),
-            api_base_url=_string_field(payload, "api_base_url"),
-            api_key=_string_field(payload, "api_key"),
-            model=_string_field(payload, "model"),
-            small_fast_model=_string_field(payload, "small_fast_model"),
-            configure=configure,
-            install_agent=_bool_field(payload, "install_agent"),
-            # The GUI's existing-account path still completes the selected
-            # Agent workflow and records a non-secret environment profile.
-            # check_agent_only is reserved for the explicit CLI flag.
-            check_agent_only=False,
-            skip_test=_bool_field(payload, "skip_test"),
-            locked_version=_bool_field(payload, "locked_version"),
-            latest=_bool_field(payload, "latest"),
-            registry=_string_field(payload, "registry"),
-            channel="gui",
-            timeout=_timeout_field(payload),
-        ),
-        _runtime(),
-    )
-
-
-class Handler(BaseHTTPRequestHandler):
-    def log_message(self, *_args) -> None:
-        return
-
-    def do_GET(self) -> None:
-        try:
-            path = urlsplit(self.path).path
-            if path == "/api/status":
-                json_response(self, 200, status_payload(_runtime()))
-                return
-            if path == "/api/profiles":
-                json_response(self, 200, profiles_payload(_runtime()))
-                return
-            if path == "/favicon.ico" and not (static_root() / "favicon.ico").exists():
-                self.send_response(204)
-                self.end_headers()
-                return
-            static_response(self, self.path)
-        except Exception as exc:
-            error_response(self, exc)
-
-    def do_POST(self) -> None:
-        try:
-            assert_session(self)
-            payload = read_json(self)
-            if self.path == "/api/probe":
-                json_response(self, 200, probe_payload(payload))
-            elif self.path == "/api/models":
-                json_response(self, 200, models_payload(payload))
-            elif self.path == "/api/install":
-                json_response(self, 200, install_payload(payload))
-            elif self.path == "/api/profiles":
-                json_response(self, 200, save_profile_payload(payload))
-            elif (agent_id := _agent_activate_match(self.path)) is not None:
-                json_response(self, 200, activate_agent_payload(agent_id, payload))
-            elif self.path == "/api/open-register":
-                provider = _string_field(payload, "provider", "ppio")
-                url = provider_home(provider)
-                agents = _agents_field(payload)
-                query = f"?agent={quote(','.join(agents))}&provider={quote(provider)}&channel=gui"
-                target = url + query
-                if os.environ.get("ONEAGENT_DISABLE_BROWSER") != "1":
-                    webbrowser.open(target)
-                json_response(self, 200, {"ok": True, "url": target, "message": f"Opened {url}"})
-            else:
-                raise OneAgentError("INVALID_REQUEST", "API route not found", status=404)
-        except Exception as exc:
-            error_response(self, exc)
-
-
-class OneAgentHTTPServer(HTTPServer):
-    session_token: str
-
-    def server_bind(self) -> None:
-        # http.server's server_bind() resolves the bind address through
-        # socket.getfqdn(), a reverse DNS lookup that blocks until it times out
-        # on hosts with no reverse resolver -- offline machines, locked-down
-        # networks and CI runners, which is exactly where OneAgent runs. It only
-        # populates self.server_name, which OneAgent never reads, so bind
-        # directly and keep GUI startup instant.
-        socketserver.TCPServer.server_bind(self)
-        host, port = self.server_address[:2]
-        self.server_name = host
-        self.server_port = port
-
-
-def create_server(host: str, port: int) -> OneAgentHTTPServer:
-    if host != "127.0.0.1":
-        raise OneAgentError("INVALID_REQUEST", "Refusing to bind outside 127.0.0.1")
-    server = OneAgentHTTPServer((host, port), Handler)
-    server.session_token = secrets.token_urlsafe(32)
-    return server
-
-
-def main(argv: list[str] | None = None) -> None:
-    parser = argparse.ArgumentParser(description="OneAgent local GUI")
-    parser.add_argument("--host", default="127.0.0.1")
-    parser.add_argument("--port", type=int, default=0)
-    parser.add_argument("--no-open", action="store_true")
-    args = parser.parse_args(argv)
-    try:
-        server = create_server(args.host, args.port)
-    except OneAgentError as exc:
-        raise SystemExit(exc.message) from exc
-    url = f"http://{args.host}:{server.server_port}/"
-    print(url, flush=True)
-    if not args.no_open:
-        webbrowser.open(url)
-    try:
-        server.serve_forever()
-    except KeyboardInterrupt:
-        pass
-    finally:
-        server.server_close()
-
-
-if __name__ == "__main__":
-    main()
diff --git a/packaging/generate_notices.py b/packaging/generate_notices.py
deleted file mode 100644
index 6ce638b3..00000000
--- a/packaging/generate_notices.py
+++ /dev/null
@@ -1,149 +0,0 @@
-from __future__ import annotations
-
-import json
-import re
-import shutil
-import sys
-from pathlib import Path
-from typing import Any
-
-
-ROOT = Path(__file__).resolve().parents[1]
-FRONTEND = ROOT / "frontend"
-
-
-def _license_name(value: object) -> str:
-    if isinstance(value, str):
-        return value
-    if isinstance(value, dict):
-        return str(value.get("type") or value.get("name") or "Unknown")
-    if isinstance(value, list):
-        return ", ".join(_license_name(item) for item in value)
-    return "Unknown"
-
-
-def _safe_name(value: str) -> str:
-    return re.sub(r"[^A-Za-z0-9._-]+", "_", value).strip("_")
-
-
-def _repository(value: object) -> str:
-    if isinstance(value, str):
-        return value
-    if isinstance(value, dict):
-        return str(value.get("url") or "")
-    return ""
-
-
-def _copy_license(package_dir: Path, destination: Path, label: str) -> str:
-    candidates = sorted(
-        path
-        for path in package_dir.iterdir()
-        if path.is_file() and re.match(r"^(licen[cs]e|copying|notice)(\..*)?$", path.name, re.IGNORECASE)
-    ) if package_dir.is_dir() else []
-    if not candidates:
-        return ""
-    target = destination / f"{_safe_name(label)}{candidates[0].suffix or '.txt'}"
-    shutil.copy2(candidates[0], target)
-    return target.name
-
-
-def npm_packages(license_dir: Path) -> list[dict[str, str]]:
-    lock_path = FRONTEND / "package-lock.json"
-    if not lock_path.exists():
-        return []
-    lock = json.loads(lock_path.read_text(encoding="utf-8"))
-    packages: list[dict[str, str]] = []
-    for relative, lock_meta in sorted(lock.get("packages", {}).items()):
-        if not relative.startswith("node_modules/") or lock_meta.get("dev"):
-            continue
-        package_dir = FRONTEND / relative
-        package_json = package_dir / "package.json"
-        if not package_json.exists():
-            continue
-        meta = json.loads(package_json.read_text(encoding="utf-8"))
-        name = str(meta.get("name") or relative.removeprefix("node_modules/"))
-        version = str(meta.get("version") or lock_meta.get("version") or "unknown")
-        packages.append(
-            {
-                "name": name,
-                "version": version,
-                "license": _license_name(meta.get("license") or meta.get("licenses")),
-                "source": str(meta.get("homepage") or _repository(meta.get("repository")) or ""),
-                "license_file": _copy_license(package_dir, license_dir, f"npm-{name}-{version}"),
-            }
-        )
-    return packages
-
-
-def agent_targets() -> list[dict[str, str]]:
-    manifest = json.loads((ROOT / "agents.lock.json").read_text(encoding="utf-8"))
-    targets = []
-    for agent_id, meta in manifest["agents"].items():
-        package = meta.get("package")
-        if not package:
-            continue
-        targets.append(
-            {
-                "id": agent_id,
-                "name": str(meta["name"]),
-                "package": f"{package['name']}@{package['version']}",
-                "license": str(package["license"]),
-                "source": str(package["source"]),
-                "license_url": str(package["license_url"]),
-            }
-        )
-    return targets
-
-
-def generate(output_dir: Path) -> Path:
-    output_dir.mkdir(parents=True, exist_ok=True)
-    license_dir = output_dir / "licenses" / "npm"
-    license_dir.mkdir(parents=True, exist_ok=True)
-    npm = npm_packages(license_dir)
-    agents = agent_targets()
-
-    lines = [
-        "# OneAgent Third-Party Notices",
-        "",
-        "This file lists software included in the OneAgent runtime and Agent installation targets referenced by the lock manifest.",
-        "Agent packages are not bundled in OneAgent; they are installed from the listed upstream source only after user confirmation.",
-        "",
-        "## Runtime Components",
-        "",
-        f"- Python {sys.version_info.major}.{sys.version_info.minor}: PSF License, <https://www.python.org/psf-landing/>",
-        "- PyInstaller bootloader: GPL-2.0-or-later with special exception, <https://pyinstaller.org/en/stable/license.html>",
-        "",
-        "## Frontend Runtime Packages",
-        "",
-        "| Package | Version | License | Source | Bundled license file |",
-        "| --- | --- | --- | --- | --- |",
-    ]
-    for package in npm:
-        lines.append(
-            f"| `{package['name']}` | `{package['version']}` | {package['license']} | {package['source'] or 'package metadata'} | {package['license_file'] or 'not provided by package'} |"
-        )
-    lines.extend(
-        [
-            "",
-            "## Agent Installation Targets (Not Bundled)",
-            "",
-            "| Agent | Locked package | License | Source | License reference |",
-            "| --- | --- | --- | --- | --- |",
-        ]
-    )
-    for agent in agents:
-        lines.append(
-            f"| {agent['name']} | `{agent['package']}` | {agent['license']} | {agent['source']} | {agent['license_url']} |"
-        )
-    path = output_dir / "THIRD_PARTY_NOTICES.md"
-    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
-    return path
-
-
-def main() -> None:
-    output = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else ROOT / "build" / "metadata"
-    print(generate(output))
-
-
-if __name__ == "__main__":
-    main()
diff --git a/packaging/oneagent.spec b/packaging/oneagent.spec
deleted file mode 100644
index 60e6268f..00000000
--- a/packaging/oneagent.spec
+++ /dev/null
@@ -1,59 +0,0 @@
-# -*- mode: python ; coding: utf-8 -*-
-
-from pathlib import Path
-
-
-ROOT = Path(SPECPATH).resolve().parent
-METADATA = ROOT / "build" / "metadata"
-
-datas = [
-    (str(ROOT / "agents.lock.json"), "."),
-    (str(ROOT / "frontend" / "dist"), "frontend/dist"),
-    (str(ROOT / "README.md"), "."),
-    (str(METADATA / "THIRD_PARTY_NOTICES.md"), "."),
-    (str(METADATA / "licenses"), "licenses"),
-]
-
-analysis = Analysis(
-    [str(ROOT / "oneagent" / "entrypoint.py")],
-    pathex=[str(ROOT)],
-    binaries=[],
-    datas=datas,
-    hiddenimports=[],
-    hookspath=[],
-    hooksconfig={},
-    runtime_hooks=[],
-    excludes=["tkinter", "unittest", "doctest"],
-    noarchive=False,
-    optimize=1,
-)
-
-pyz = PYZ(analysis.pure)
-
-exe = EXE(
-    pyz,
-    analysis.scripts,
-    [],
-    exclude_binaries=True,
-    name="OneAgent",
-    debug=False,
-    bootloader_ignore_signals=False,
-    strip=False,
-    upx=False,
-    console=True,
-    disable_windowed_traceback=False,
-    argv_emulation=False,
-    target_arch=None,
-    codesign_identity=None,
-    entitlements_file=None,
-)
-
-collection = COLLECT(
-    exe,
-    analysis.binaries,
-    analysis.datas,
-    strip=False,
-    upx=False,
-    upx_exclude=[],
-    name="OneAgent",
-)
diff --git a/distribution/providers.json b/providers.lock.json
similarity index 65%
rename from distribution/providers.json
rename to providers.lock.json
index 20a64173..91cb0e76 100644
--- a/distribution/providers.json
+++ b/providers.lock.json
@@ -1,9 +1,13 @@
 {
   "schema_version": 1,
+  "default_fallback_probe_model": "deepseek/deepseek-v3",
   "providers": {
     "ppio": {
       "name": "PPIO",
       "home": "https://ppio.com/",
+      "base_url": "https://api.ppio.com/openai",
+      "anthropic_base_url": "https://api.ppio.com/anthropic",
+      "fallback_probe_model": "deepseek/deepseek-v3",
       "relationship": "none",
       "disclosure": "",
       "referral_url": "",
@@ -17,6 +21,9 @@
     "novita": {
       "name": "Novita",
       "home": "https://novita.ai/",
+      "base_url": "https://api.novita.ai/openai",
+      "anthropic_base_url": "https://api.novita.ai/anthropic",
+      "fallback_probe_model": "deepseek/deepseek_v3",
       "relationship": "none",
       "disclosure": "",
       "referral_url": "",
diff --git a/pyproject.toml b/pyproject.toml
deleted file mode 100644
index 94d6da59..00000000
--- a/pyproject.toml
+++ /dev/null
@@ -1,35 +0,0 @@
-[build-system]
-requires = ["setuptools>=75"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "oneagent-launcher"
-version = "0.2.0.dev0"
-description = "Cross-platform local AI development environment activator"
-readme = "README.md"
-requires-python = ">=3.12"
-dependencies = []
-
-[project.scripts]
-oneagent = "oneagent.cli:main"
-oneagent-gui = "oneagent.server:main"
-
-[tool.setuptools]
-packages = ["oneagent"]
-
-# Staged by setup.py's build_py hook; see that module for why they are copied
-# instead of read from the repository root.
-[tool.setuptools.package-data]
-oneagent = ["_resources/agents.lock.json", "_resources/frontend/dist/**/*"]
-
-[tool.coverage.run]
-branch = true
-source = ["oneagent"]
-
-[tool.coverage.report]
-show_missing = true
-skip_covered = false
-fail_under = 85
-
-[tool.coverage.json]
-output = "build/coverage/coverage.json"
diff --git a/runtimes.lock.json b/runtimes.lock.json
new file mode 100644
index 00000000..e47b34a6
--- /dev/null
+++ b/runtimes.lock.json
@@ -0,0 +1,118 @@
+{
+  "schema_version": 1,
+  "runtimes": {
+    "node": {
+      "name": "Node.js",
+      "version": "24.18.1",
+      "commands": ["node", "npm", "npx"],
+      "probe_command": "npm",
+      "license": "MIT",
+      "license_url": "https://github.com/nodejs/node/blob/main/LICENSE",
+      "source": "https://nodejs.org/dist/",
+      "artifacts": {
+        "macos-arm64": {
+          "url": "https://nodejs.org/dist/v24.18.1/node-v24.18.1-darwin-arm64.tar.gz",
+          "mirror_url": "https://cdn.npmmirror.com/binaries/node/v24.18.1/node-v24.18.1-darwin-arm64.tar.gz",
+          "sha256": "eb02f7fab96d3d67de40c5ec8566096fcb4c2026728787683ae5a97eb612b941",
+          "archive": "tar.gz",
+          "strip_root": true,
+          "bin_dir": "bin"
+        },
+        "macos-x64": {
+          "url": "https://nodejs.org/dist/v24.18.1/node-v24.18.1-darwin-x64.tar.gz",
+          "mirror_url": "https://cdn.npmmirror.com/binaries/node/v24.18.1/node-v24.18.1-darwin-x64.tar.gz",
+          "sha256": "6fb20fceacbb157c2f95825b80df4a454a0f6d81cdcd7bb81eeae9147e0e76ec",
+          "archive": "tar.gz",
+          "strip_root": true,
+          "bin_dir": "bin"
+        },
+        "windows-x64": {
+          "url": "https://nodejs.org/dist/v24.18.1/node-v24.18.1-win-x64.zip",
+          "mirror_url": "https://cdn.npmmirror.com/binaries/node/v24.18.1/node-v24.18.1-win-x64.zip",
+          "sha256": "ec56b84a7551893ab2324ebdfdc4ab974a63b4781162600b68a1293cc3e53765",
+          "archive": "zip",
+          "strip_root": true,
+          "bin_dir": "."
+        },
+        "windows-arm64": {
+          "url": "https://nodejs.org/dist/v24.18.1/node-v24.18.1-win-arm64.zip",
+          "mirror_url": "https://cdn.npmmirror.com/binaries/node/v24.18.1/node-v24.18.1-win-arm64.zip",
+          "sha256": "ffbc7d3e1baf6804f7431ff94f19b9a885a650568c93ea4ccb1bb0038f6af825",
+          "archive": "zip",
+          "strip_root": true,
+          "bin_dir": "."
+        },
+        "linux-x64": {
+          "url": "https://nodejs.org/dist/v24.18.1/node-v24.18.1-linux-x64.tar.gz",
+          "mirror_url": "https://cdn.npmmirror.com/binaries/node/v24.18.1/node-v24.18.1-linux-x64.tar.gz",
+          "sha256": "9f5eb6ac21845a66c493c91a253b1da32fd684e89e9b7202d4936982336be4ca",
+          "archive": "tar.gz",
+          "strip_root": true,
+          "bin_dir": "bin"
+        },
+        "linux-arm64": {
+          "url": "https://nodejs.org/dist/v24.18.1/node-v24.18.1-linux-arm64.tar.gz",
+          "mirror_url": "https://cdn.npmmirror.com/binaries/node/v24.18.1/node-v24.18.1-linux-arm64.tar.gz",
+          "sha256": "df224555a083b918e46260cc969838501b9f9a87140c1195e5b9597b56d5dae2",
+          "archive": "tar.gz",
+          "strip_root": true,
+          "bin_dir": "bin"
+        }
+      }
+    },
+    "uv": {
+      "name": "uv",
+      "version": "0.12.1",
+      "commands": ["uv", "uvx"],
+      "probe_command": "uv",
+      "license": "MIT OR Apache-2.0",
+      "license_url": "https://github.com/astral-sh/uv/blob/main/LICENSE-APACHE",
+      "source": "https://github.com/astral-sh/uv/releases",
+      "note": "uv manages its own CPython download for Aider; OneAgent does not fetch Python directly.",
+      "artifacts": {
+        "macos-arm64": {
+          "url": "https://github.com/astral-sh/uv/releases/download/0.12.1/uv-aarch64-apple-darwin.tar.gz",
+          "sha256": "77d2906988e8074fd43f2f329ec452ebbf9b0c257ba1c66451c71de70a6baf42",
+          "archive": "tar.gz",
+          "strip_root": true,
+          "bin_dir": "."
+        },
+        "macos-x64": {
+          "url": "https://github.com/astral-sh/uv/releases/download/0.12.1/uv-x86_64-apple-darwin.tar.gz",
+          "sha256": "69d9f9a00337f25a50dcb13882052da08b8469bac11091c98c5694c3c6721467",
+          "archive": "tar.gz",
+          "strip_root": true,
+          "bin_dir": "."
+        },
+        "windows-x64": {
+          "url": "https://github.com/astral-sh/uv/releases/download/0.12.1/uv-x86_64-pc-windows-msvc.zip",
+          "sha256": "8fcb0cb46e1229065e344758980924e569bef5882ef45f46fada8fb24e06b74a",
+          "archive": "zip",
+          "strip_root": false,
+          "bin_dir": "."
+        },
+        "windows-arm64": {
+          "url": "https://github.com/astral-sh/uv/releases/download/0.12.1/uv-aarch64-pc-windows-msvc.zip",
+          "sha256": "9bc7c18e616230fa2dc6fb24bc3afde18a95c2b5c9433de747e9502c66041568",
+          "archive": "zip",
+          "strip_root": false,
+          "bin_dir": "."
+        },
+        "linux-x64": {
+          "url": "https://github.com/astral-sh/uv/releases/download/0.12.1/uv-x86_64-unknown-linux-gnu.tar.gz",
+          "sha256": "90b2f223fb69d19db49e117da601f64978593417988530aa733d456141b4bcbb",
+          "archive": "tar.gz",
+          "strip_root": true,
+          "bin_dir": "."
+        },
+        "linux-arm64": {
+          "url": "https://github.com/astral-sh/uv/releases/download/0.12.1/uv-aarch64-unknown-linux-gnu.tar.gz",
+          "sha256": "769d373e146692c639b5fbaae33b331c297a32e03d30448772051902df52bbf4",
+          "archive": "tar.gz",
+          "strip_root": true,
+          "bin_dir": "."
+        }
+      }
+    }
+  }
+}
diff --git a/scripts/agent_config_adopted_check.py b/scripts/agent_config_adopted_check.py
deleted file mode 100644
index 7ad2bf0a..00000000
--- a/scripts/agent_config_adopted_check.py
+++ /dev/null
@@ -1,274 +0,0 @@
-#!/usr/bin/env python3
-"""Verify, without any API key, that a configured Agent adopts what we wrote.
-
-The layer below this one proves an Agent installs and that its config file has
-the right shape; agent_e2e_smoke.py proves an Agent answers a real request but
-needs a real key. Neither ran where the Claude Code defect was found: an Agent
-OneAgent reported as ``configured`` that answered ``Not logged in`` the moment
-it started, because the credential never reached it.
-
-The trick here is that telling adopted from not-adopted does not need a key.
-Point the configuration at the discard port (127.0.0.1:9, nothing listens) with
-a dummy credential and run the Agent:
-
-* an adopted configuration fails at the network layer -- ``provider: oneagent``
-  followed by ``Reconnecting`` for Codex, a connection-refused error for Claude
-  Code -- because the Agent read our config and tried to reach our endpoint;
-* an ignored configuration fails at the auth/login layer first -- ``Not logged
-  in`` -- before any connection is attempted.
-
-A valid key would still only ever produce a connection failure at the discard
-port, so the dummy credential is enough to separate the two outcomes. This is
-exactly the pair of results that distinguished the bug, which is why the check
-belongs in automation rather than a manual smoke.
-
-Two layers, mirroring the rest of the verification design:
-
-* ``classify_adoption`` is pure and is unit-tested in ordinary CI against the
-  two real-world outputs, so the discriminator itself is covered everywhere;
-* running the actual Agents needs them installed, so it happens here, in the
-  release-candidate workflow that already installs Agents -- but keylessly,
-  removing the real-key threshold that let the defect through.
-
-Usage::
-
-    python3.12 scripts/agent_config_adopted_check.py
-    python3.12 scripts/agent_config_adopted_check.py --agents codex,claude-code
-"""
-from __future__ import annotations
-
-import argparse
-import shlex
-import shutil
-import subprocess
-import sys
-import tempfile
-from dataclasses import dataclass
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[1]
-if str(ROOT) not in sys.path:
-    sys.path.insert(0, str(ROOT))
-
-from oneagent.catalog import agent_catalog
-from oneagent.installer import InstallOptions, agent_env_path, install_many, redact
-from scripts.verify_locked_agents import create_isolated_runtime
-
-DEFAULT_AGENTS = ("codex", "claude-code")
-# Port 9 is the discard service: nothing answers, so every adopted configuration
-# fails with a connection error rather than a real response.
-DISCARD_BASE_URL = "http://127.0.0.1:9"
-DUMMY_API_KEY = "oneagent-discard-key"
-DISCARD_MODEL = "oneagent-discard-model"
-PROMPT = "Reply with the single word: ready"
-
-# Output that means the Agent rejected the credential or never read the config
-# we wrote -- the configuration was NOT adopted. These are the signatures of the
-# "Not logged in" defect: the Agent talks about auth or login, which only
-# happens when our configuration did not reach it. Checked first, so a verbose
-# error that mentions both layers is reported as the failure it is.
-NOT_ADOPTED_MARKERS = (
-    "not logged in",
-    "please run /login",
-    "please login",
-    "login required",
-    "requires authentication",
-    "authentication required",
-    "no api key",
-    "api key not found",
-    "missing api key",
-    "invalid api key",
-    "unauthorized",
-    "no credentials",
-)
-
-# Output that means the Agent read our configuration and tried to reach the
-# endpoint we pointed it at -- the configuration WAS adopted. Against the
-# discard port this is the passing outcome.
-ADOPTED_MARKERS = (
-    "provider: oneagent",  # Codex echoes the provider section it adopted
-    "reconnecting",
-    "connection refused",
-    "connect econnrefused",
-    "econnrefused",
-    "connection reset",
-    "could not connect",
-    "failed to connect",
-    "cannot connect",
-    "fetch failed",  # Claude Code's Node client wrapping a socket error
-    "network error",
-    "unreachable",
-    "could not resolve host",
-    "name or service not known",
-    "nodename nor servname",  # macOS getaddrinfo wording
-    "os error 61",  # macOS: connection refused
-    "os error 111",  # linux: connection refused
-)
-
-
-def classify_adoption(output: str) -> tuple[bool, str]:
-    """Decide whether an Agent's output shows it adopted the configuration.
-
-    Returns ``(adopted, reason)``. The discard port makes the two outcomes
-    mutually exclusive -- an adopted config fails at the network layer, an
-    ignored one at the auth layer -- so no real key is needed to tell them
-    apart. Auth markers win: when in doubt, report the configuration as not
-    adopted rather than pass a check that means nothing.
-    """
-    lowered = output.lower()
-    for marker in NOT_ADOPTED_MARKERS:
-        if marker in lowered:
-            return False, f"auth/login error, config not adopted ({marker!r})"
-    for marker in ADOPTED_MARKERS:
-        if marker in lowered:
-            return True, f"connection failure, config adopted ({marker!r})"
-    return False, "output shows neither a connection failure nor an auth error"
-
-
-def parse_env_file(path: Path) -> dict[str, str]:
-    """Read the ``export``/``$env:`` assignments an Agent's env file holds.
-
-    Sourcing this file is what the next-step hint tells the user to do; loading
-    the same pairs into the child environment reproduces it without a shell.
-    """
-    values: dict[str, str] = {}
-    for raw_line in path.read_text(encoding="utf-8").splitlines():
-        line = raw_line.strip()
-        if line.startswith("export "):
-            name, sep, raw = line[len("export "):].partition("=")
-            if not sep:
-                continue
-            try:
-                parsed = shlex.split(raw)
-                values[name.strip()] = parsed[0] if parsed else ""
-            except ValueError:
-                values[name.strip()] = raw.strip().strip("'\"")
-        elif line.startswith("$env:"):
-            name, sep, raw = line[len("$env:"):].partition("=")
-            if sep:
-                values[name.strip()] = raw.strip().strip("'\"")
-    return values
-
-
-@dataclass
-class Outcome:
-    agent: str
-    step: str
-    ok: bool | None  # None marks a skip rather than a pass or a failure
-    detail: str
-
-
-def configure_discard(runtime, agents: list[str]) -> dict:
-    """Install the Agents and point them at the discard port with a dummy key.
-
-    skip_test is deliberate: the discard port cannot answer a protocol probe,
-    and the probe is not what this layer verifies -- adopting the config is.
-    """
-    return install_many(
-        InstallOptions(
-            agents=list(agents),
-            provider="custom",
-            api_base_url=DISCARD_BASE_URL,
-            api_key=DUMMY_API_KEY,
-            model=DISCARD_MODEL,
-            configure=True,
-            install_agent=True,
-            locked_version=True,
-            skip_test=True,
-            home=runtime.home,
-            os_id=runtime.os_id,
-            timeout=900,
-        ),
-        runtime,
-    )
-
-
-# One-shot, non-interactive invocations: both Agents default to a REPL and would
-# wait for input until the timeout. Add an Agent's line here when it gains a
-# config adapter -- this is launch syntax, which is code, not lock data.
-ONE_SHOT_ARGV = {
-    "codex": lambda exe: [exe, "exec", PROMPT],
-    "claude-code": lambda exe: [exe, "-p", PROMPT],
-}
-
-
-def exercise(agent_id: str, runtime, timeout: int) -> Outcome:
-    meta = agent_catalog()[agent_id]
-    command = str(meta["command"])
-    executable = runtime.which(command)
-    build_argv = ONE_SHOT_ARGV.get(agent_id)
-    if not executable or build_argv is None:
-        return Outcome(agent_id, "run", None, f"{command} not exercisable here; skipped")
-    env = dict(runtime.env)
-    env_file = agent_env_path(runtime, agent_id)
-    if env_file.is_file():
-        # Reproduce `source <env file>`: the credential route under test.
-        env.update(parse_env_file(env_file))
-    env.update({"CI": "1", "NO_COLOR": "1", "TERM": "dumb", "LANG": "C"})
-    try:
-        result = subprocess.run(
-            build_argv(executable),
-            text=True,
-            capture_output=True,
-            timeout=timeout,
-            env=env,
-            cwd=str(runtime.home),
-        )
-    except subprocess.TimeoutExpired:
-        return Outcome(agent_id, "run", False, f"no output within {timeout}s; cannot confirm adoption")
-    output = ((result.stdout or "") + (result.stderr or "")).strip()
-    adopted, reason = classify_adoption(output)
-    tail = redact(" ".join(output.split())[-200:], [DUMMY_API_KEY])
-    return Outcome(agent_id, "run", adopted, f"{reason} | {tail}" if tail else reason)
-
-
-def run_check(agents: list[str], timeout: int) -> list[Outcome]:
-    root = Path(tempfile.mkdtemp(prefix="oneagent-adopt-"))
-    outcomes: list[Outcome] = []
-    try:
-        runtime = create_isolated_runtime(root)
-        result = configure_discard(runtime, agents)
-        for entry in result.get("results", []):
-            agent = str(entry.get("agent"))
-            status = str(entry.get("status"))
-            ok = status in {"configured", "installed"}
-            outcomes.append(Outcome(agent, "configure", ok, status or str(entry.get("message"))))
-        if not result.get("ok"):
-            detail = redact(" ".join(str(result.get("log", "")).split())[-300:], [DUMMY_API_KEY])
-            outcomes.append(Outcome("-", "configure", False, detail or "configuration did not complete"))
-        else:
-            for agent_id in agents:
-                outcomes.append(exercise(agent_id, runtime, timeout))
-    finally:
-        shutil.rmtree(root, ignore_errors=True)
-    return outcomes
-
-
-def main(argv: list[str] | None = None) -> None:
-    parser = argparse.ArgumentParser(
-        description="Keyless check that configured Agents adopt the configuration OneAgent wrote"
-    )
-    parser.add_argument("--agents", default=",".join(DEFAULT_AGENTS), help="Comma-separated Agent IDs")
-    parser.add_argument("--timeout", type=int, default=120, help="Seconds to wait per Agent run")
-    args = parser.parse_args(argv)
-    agents = [item.strip() for item in args.agents.split(",") if item.strip()]
-
-    outcomes = run_check(agents, args.timeout)
-    print()
-    width = max(len(item.agent) for item in outcomes)
-    for item in outcomes:
-        mark = "PASS" if item.ok else ("SKIP" if item.ok is None else "FAIL")
-        print(f"[{mark}] {item.agent:<{width}}  {item.step:<10} {item.detail}")
-
-    failures = [item for item in outcomes if item.ok is False]
-    if failures:
-        raise SystemExit(f"\n{len(failures)} check(s) failed")
-    exercised = [item for item in outcomes if item.step == "run" and item.ok is True]
-    if not exercised:
-        print("\nNo Agent could be exercised; nothing verified.")
-    else:
-        print(f"\n{len(exercised)} Agent(s) adopted the configuration with no API key in play.")
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/agent_e2e_smoke.py b/scripts/agent_e2e_smoke.py
deleted file mode 100755
index 1d83b31f..00000000
--- a/scripts/agent_e2e_smoke.py
+++ /dev/null
@@ -1,201 +0,0 @@
-#!/usr/bin/env python3
-"""Ask Codex and Claude Code to actually answer something.
-
-The layer below this one proves an Agent installs, resolves on PATH and reports
-the locked version, and the Python suites prove the config file has the right
-shape. None of that proves the Agent works: a config can be structurally perfect
-and still name an endpoint the Agent rejects, or a model the account cannot use.
-Running the Agent is the only judge of "usable".
-
-Needs a real key, so it never runs in ordinary CI:
-
-    ONEAGENT_API_KEY=... python3.12 scripts/agent_e2e_smoke.py --provider ppio
-    ONEAGENT_API_KEY=... python3.12 scripts/agent_e2e_smoke.py \
-        --provider custom --api-base-url https://example.com/openai
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import shutil
-import subprocess
-import sys
-import tempfile
-from dataclasses import dataclass
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[1]
-if str(ROOT) not in sys.path:
-    sys.path.insert(0, str(ROOT))
-
-from oneagent.catalog import agent_catalog
-from oneagent.installer import InstallOptions, Runtime, install_many, redact
-
-# Codex speaks Responses and Claude Code speaks Anthropic Messages, so a key that
-# satisfies one can still fail the other -- which is why both are exercised
-# rather than one standing in for the pair.
-AGENTS = ("codex", "claude-code")
-PROMPT = "Reply with the single word: ready"
-
-
-@dataclass
-class Outcome:
-    agent: str
-    step: str
-    ok: bool
-    detail: str
-
-
-def run(argv: list[str], *, env: dict[str, str], timeout: int, cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
-    return subprocess.run(
-        argv, text=True, capture_output=True, timeout=timeout, env=env, cwd=str(cwd) if cwd else None
-    )
-
-
-def configure(home: Path, provider: str, api_base_url: str, api_key: str, model: str, timeout: int) -> dict:
-    """Full install_many, protocol probe included -- no --skip-test here."""
-    return install_many(
-        InstallOptions(
-            agents=list(AGENTS),
-            provider=provider,
-            api_base_url=api_base_url,
-            api_key=api_key,
-            model=model,
-            configure=True,
-            skip_test=False,
-            home=home,
-            timeout=timeout,
-        ),
-        Runtime.create(home=home),
-    )
-
-
-def check_written_config(home: Path) -> list[Outcome]:
-    """Each adapter writes a different shape; check what it actually promises."""
-    results: list[Outcome] = []
-
-    codex_config = home / ".codex" / "config.toml"
-    if codex_config.is_file():
-        text = codex_config.read_text(encoding="utf-8")
-        env_var = "ONEAGENT_API_KEY_CODEX"
-        env_file = home / ".oneagent" / "agents" / "codex.env"
-        # Codex reads the key indirectly through env_key, so the variable it
-        # names has to exist in the file the next-step hint sources.
-        named = f'env_key = "{env_var}"' in text
-        sourced = env_file.is_file() and env_var in env_file.read_text(encoding="utf-8")
-        results.append(
-            Outcome("codex", "config", named and sourced, f"env_key named={named} present_in_env_file={sourced}")
-        )
-    else:
-        results.append(Outcome("codex", "config", False, f"missing {codex_config}"))
-
-    claude_config = home / ".claude" / "settings.json"
-    if claude_config.is_file():
-        env = json.loads(claude_config.read_text(encoding="utf-8")).get("env", {})
-        required = ["ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_MODEL", "ANTHROPIC_SMALL_FAST_MODEL"]
-        missing = [key for key in required if not env.get(key)]
-        results.append(
-            Outcome("claude-code", "config", not missing, "all four variables set" if not missing else f"missing {missing}")
-        )
-    else:
-        results.append(Outcome("claude-code", "config", False, f"missing {claude_config}"))
-    return results
-
-
-def agent_env(home: Path, agent_id: str, api_key: str) -> dict[str, str]:
-    """The environment the next-step hint tells the user to set up."""
-    env = {
-        "HOME": str(home),
-        "USERPROFILE": str(home),
-        "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
-        "LANG": "C",
-        "TERM": "dumb",
-        # Both Agents skip first-run interactive setup when told they are not on
-        # a TTY; without this they wait for input and the smoke times out.
-        "CI": "1",
-        "NO_COLOR": "1",
-    }
-    if agent_id == "codex":
-        env["ONEAGENT_API_KEY_CODEX"] = api_key
-    return env
-
-
-def exercise(agent_id: str, home: Path, api_key: str, timeout: int) -> Outcome:
-    command = agent_catalog()[agent_id]["command"]
-    executable = shutil.which(command)
-    if not executable:
-        return Outcome(agent_id, "run", False, f"{command} is not on PATH")
-    argv = {
-        # Non-interactive one-shot flags: both Agents default to a REPL.
-        "codex": [executable, "exec", PROMPT],
-        "claude-code": [executable, "-p", PROMPT],
-    }[agent_id]
-    try:
-        result = run(argv, env=agent_env(home, agent_id, api_key), timeout=timeout, cwd=home)
-    except subprocess.TimeoutExpired:
-        return Outcome(agent_id, "run", False, f"no answer within {timeout}s")
-    output = ((result.stdout or "") + (result.stderr or "")).strip()
-    detail = redact(" ".join(output.split())[-300:], [api_key])
-    if result.returncode != 0:
-        return Outcome(agent_id, "run", False, f"exit {result.returncode}: {detail}")
-    if not output:
-        return Outcome(agent_id, "run", False, "exited 0 but produced no output")
-    return Outcome(agent_id, "run", True, detail[:160])
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="End-to-end usability smoke for Codex and Claude Code")
-    parser.add_argument("--provider", default="ppio")
-    parser.add_argument("--api-base-url", default="")
-    parser.add_argument("--model", default="", help="Leave empty to let discovery choose")
-    parser.add_argument("--timeout", type=int, default=180)
-    parser.add_argument("--keep-home", action="store_true", help="Keep the temporary HOME for inspection")
-    args = parser.parse_args()
-
-    api_key = os.environ.get("ONEAGENT_API_KEY", "")
-    if not api_key:
-        raise SystemExit("ONEAGENT_API_KEY is required; this smoke needs a real credential")
-
-    home = Path(tempfile.mkdtemp(prefix="oneagent-e2e-"))
-    outcomes: list[Outcome] = []
-    try:
-        print(f"HOME: {home}")
-        print(f"provider: {args.provider}  model: {args.model or '(discovered)'}")
-
-        result = configure(home, args.provider, args.api_base_url, api_key, args.model, args.timeout)
-        log = redact(result.get("log", ""), [api_key])
-        if api_key in log:
-            outcomes.append(Outcome("-", "redaction", False, "the install log contains the API key"))
-        else:
-            outcomes.append(Outcome("-", "redaction", True, "install log carries no credential"))
-        for entry in result.get("results", []):
-            agent = str(entry.get("agent"))
-            ok = entry.get("status") in {"configured", "installed"}
-            outcomes.append(Outcome(agent, "configure", ok, str(entry.get("status"))))
-        probe = result.get("probe") or {}
-        outcomes.append(
-            Outcome("-", "probe", bool(probe.get("ok", False)), str(probe.get("message", "no probe result")))
-        )
-
-        outcomes.extend(check_written_config(home))
-        for agent_id in AGENTS:
-            outcomes.append(exercise(agent_id, home, api_key, args.timeout))
-    finally:
-        if args.keep_home:
-            print(f"kept {home}")
-        else:
-            shutil.rmtree(home, ignore_errors=True)
-
-    print()
-    width = max(len(item.agent) for item in outcomes)
-    for item in outcomes:
-        print(f"[{'PASS' if item.ok else 'FAIL'}] {item.agent:<{width}}  {item.step:<10} {item.detail}")
-    failures = [item for item in outcomes if not item.ok]
-    if failures:
-        raise SystemExit(f"\n{len(failures)} check(s) failed")
-    print("\nBoth Agents answered a real request.")
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/build_release.py b/scripts/build_release.py
deleted file mode 100755
index 556ee909..00000000
--- a/scripts/build_release.py
+++ /dev/null
@@ -1,294 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import os
-import platform
-import shutil
-import stat
-import subprocess
-import sys
-import zipfile
-from datetime import datetime, timezone
-from pathlib import Path
-
-
-ROOT = Path(__file__).resolve().parents[1]
-BUILD = ROOT / "build"
-RELEASE = ROOT / "release"
-
-
-def run(args: list[str], *, cwd: Path = ROOT) -> None:
-    subprocess.run(args, cwd=cwd, check=True)
-
-
-def resolve_tool(command: str, hint: str) -> str:
-    """Locate an external tool by absolute path.
-
-    On Windows npm is npm.cmd, and CreateProcess only appends .exe when
-    resolving a bare name, so subprocess would raise FileNotFoundError for
-    "npm". shutil.which honours PATHEXT and finds the real launcher. Never
-    fall back to a shell invocation, which the release policy forbids.
-    """
-    resolved = shutil.which(command)
-    if not resolved:
-        raise SystemExit(f"{command} was not found on PATH; {hint}")
-    return resolved
-
-
-def version() -> str:
-    namespace: dict[str, object] = {}
-    exec((ROOT / "oneagent" / "__init__.py").read_text(encoding="utf-8"), namespace)
-    return str(namespace["__version__"])
-
-
-def target() -> tuple[str, str]:
-    system = platform.system().lower()
-    os_id = "macos" if system == "darwin" else "windows" if system == "windows" else "linux"
-    machine = platform.machine().lower()
-    arch = "arm64" if machine in {"arm64", "aarch64"} else "x64"
-    return os_id, arch
-
-
-def sha256(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for block in iter(lambda: handle.read(1024 * 1024), b""):
-            digest.update(block)
-    return digest.hexdigest()
-
-
-def zip_tree(source: Path, destination: Path, root_name: str) -> None:
-    with zipfile.ZipFile(destination, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=9) as archive:
-        for path in sorted(source.rglob("*")):
-            if not path.is_file():
-                continue
-            relative = Path(root_name) / path.relative_to(source)
-            info = zipfile.ZipInfo.from_file(path, str(relative))
-            info.compress_type = zipfile.ZIP_DEFLATED
-            info.external_attr = (stat.S_IMODE(path.stat().st_mode) & 0xFFFF) << 16
-            archive.writestr(info, path.read_bytes(), compress_type=zipfile.ZIP_DEFLATED, compresslevel=9)
-
-
-def source_files() -> list[Path]:
-    roots = [
-        "oneagent",
-        "scripts",
-        "packaging",
-        "docs",
-        "distribution",
-        "tests",
-        ".github",
-        "frontend/src",
-        "frontend/e2e",
-        "frontend/dist",
-        "site/src",
-        "site/e2e",
-        "site/scripts",
-        "site/public/images",
-        "build/metadata/THIRD_PARTY_NOTICES.md",
-        "build/metadata/licenses",
-    ]
-    # Directories whose contents a build regenerates. site/src/generated holds
-    # the public release index, which carries the checksums of one machine's
-    # artifacts; shipping it inside the source archive would contradict the
-    # reason ADR-006 generates that file instead of tracking it.
-    excluded = {"__pycache__", "generated"}
-    files: list[Path] = []
-    for item in roots:
-        path = ROOT / item
-        if path.is_file():
-            files.append(path)
-        elif path.exists():
-            files.extend(
-                candidate
-                for candidate in path.rglob("*")
-                if candidate.is_file() and not excluded & set(candidate.parts)
-            )
-    for item in [
-        ".dockerignore",
-        "Dockerfile.test",
-        "README.md",
-        "agents.lock.json",
-        "pyproject.toml",
-        "frontend/package.json",
-        "frontend/package-lock.json",
-        "frontend/tsconfig.json",
-        "frontend/vite.config.ts",
-        "frontend/playwright.config.ts",
-        "frontend/index.html",
-        "site/package.json",
-        "site/package-lock.json",
-        "site/tsconfig.json",
-        "site/astro.config.mjs",
-        "site/vitest.config.ts",
-        "site/playwright.config.ts",
-        "site/public/favicon.svg",
-        "site/public/_headers",
-    ]:
-        path = ROOT / item
-        if path.exists():
-            files.append(path)
-    return sorted(set(files))
-
-
-def build_source_zip(current_version: str) -> Path:
-    destination = RELEASE / f"OneAgent-{current_version}-source.zip"
-    root_name = f"OneAgent-{current_version}"
-    with zipfile.ZipFile(destination, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=9) as archive:
-        for path in source_files():
-            archive.write(path, Path(root_name) / path.relative_to(ROOT))
-    return destination
-
-
-def ensure_unsigned_channel(channel: str, os_id: str) -> None:
-    """Fail fast before a long build when the Stable prerequisites are absent.
-
-    This is only a pre-flight check. Whether the produced binary carries a real
-    signature is decided by verify_stable_signature() against the artifact
-    itself, because an environment variable proves nothing.
-    """
-    if channel != "stable":
-        return
-    if os_id == "macos" and os.environ.get("ONEAGENT_MACOS_SIGNED") != "1":
-        raise SystemExit("Stable macOS builds require signing and notarization evidence")
-    if os_id == "windows" and os.environ.get("ONEAGENT_WINDOWS_SIGNED") != "1":
-        raise SystemExit("Stable Windows builds require Authenticode signing evidence")
-
-
-def _signature_check(args: list[str], failure: str) -> None:
-    try:
-        result = subprocess.run(args, cwd=ROOT, capture_output=True, text=True)
-    except OSError as exc:
-        raise SystemExit(f"{failure}: cannot run {args[0]}: {exc}") from exc
-    if result.returncode != 0:
-        detail = (result.stderr or result.stdout or "").strip().splitlines()
-        raise SystemExit(f"{failure}: {detail[-1] if detail else f'{args[0]} exit {result.returncode}'}")
-
-
-def verify_stable_signature(channel: str, os_id: str, bundle: Path) -> None:
-    """Prove the Stable artifact is really signed.
-
-    The previous gate only read ONEAGENT_MACOS_SIGNED / ONEAGENT_WINDOWS_SIGNED,
-    so exporting either variable was enough to publish an unsigned build as
-    Stable -- the exact "degrade into a fake pass" failure the release policy
-    forbids. Interrogate the binary instead.
-    """
-    if channel != "stable":
-        return
-    if os_id == "macos":
-        _signature_check(
-            ["codesign", "--verify", "--deep", "--strict", "--verbose=2", str(bundle)],
-            "Stable macOS builds require a valid Developer ID signature",
-        )
-        _signature_check(
-            ["spctl", "--assess", "--type", "execute", str(bundle)],
-            "Stable macOS builds must pass Gatekeeper assessment",
-        )
-        _signature_check(
-            ["xcrun", "stapler", "validate", str(bundle)],
-            "Stable macOS builds require a stapled notarization ticket",
-        )
-    elif os_id == "windows":
-        executable = bundle / "OneAgent.exe"
-        _signature_check(
-            [
-                "powershell",
-                "-NoProfile",
-                "-NonInteractive",
-                "-Command",
-                "$ErrorActionPreference='Stop';"
-                f" $signature = Get-AuthenticodeSignature -LiteralPath '{executable}';"
-                " if ($signature.Status -ne 'Valid') { Write-Error \"Authenticode status:"
-                " $($signature.Status)\"; exit 1 }",
-            ],
-            "Stable Windows builds require a valid Authenticode signature",
-        )
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Build a platform-native OneAgent onedir archive")
-    parser.add_argument("--channel", choices=["technical-preview-unsigned", "stable"], default="technical-preview-unsigned")
-    parser.add_argument("--skip-frontend", action="store_true")
-    parser.add_argument("--source", action="store_true", help="Also create the source ZIP")
-    args = parser.parse_args()
-
-    os_id, arch = target()
-    ensure_unsigned_channel(args.channel, os_id)
-    current_version = version()
-    RELEASE.mkdir(parents=True, exist_ok=True)
-    (BUILD / "metadata").mkdir(parents=True, exist_ok=True)
-
-    if not args.skip_frontend:
-        npm = resolve_tool("npm", "install Node.js or pass --skip-frontend with a prebuilt frontend/dist")
-        run([npm, "run", "build"], cwd=ROOT / "frontend")
-    if not (ROOT / "frontend" / "dist" / "index.html").exists():
-        raise SystemExit("frontend/dist is missing; build the React frontend first")
-    if list((ROOT / "frontend" / "dist").rglob("*.map")):
-        raise SystemExit("Source maps are forbidden in release assets")
-
-    run([sys.executable, str(ROOT / "packaging" / "generate_notices.py"), str(BUILD / "metadata")])
-
-    dist_path = BUILD / "pyinstaller-dist"
-    work_path = BUILD / "pyinstaller-work"
-    if dist_path.exists():
-        shutil.rmtree(dist_path)
-    if work_path.exists():
-        shutil.rmtree(work_path)
-    run(
-        [
-            sys.executable,
-            "-m",
-            "PyInstaller",
-            "--noconfirm",
-            "--clean",
-            "--distpath",
-            str(dist_path),
-            "--workpath",
-            str(work_path),
-            str(ROOT / "packaging" / "oneagent.spec"),
-        ]
-    )
-
-    bundle = dist_path / "OneAgent"
-    if not bundle.is_dir():
-        raise SystemExit(f"PyInstaller output not found: {bundle}")
-    # Verify the real artifact before it is archived, so an unsigned build can
-    # never reach a Stable ZIP.
-    verify_stable_signature(args.channel, os_id, bundle)
-    artifact_name = f"OneAgent-{current_version}-{args.channel}-{os_id}-{arch}.zip"
-    artifact = RELEASE / artifact_name
-    zip_tree(bundle, artifact, "OneAgent")
-
-    artifacts = [artifact]
-    if args.source:
-        artifacts.append(build_source_zip(current_version))
-
-    lock = json.loads((ROOT / "agents.lock.json").read_text(encoding="utf-8"))
-    manifest = {
-        "schema_version": 1,
-        "oneagent_version": current_version,
-        "channel": args.channel,
-        "unsigned": args.channel == "technical-preview-unsigned",
-        "platform": os_id,
-        "arch": arch,
-        "python": platform.python_version(),
-        "built_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
-        "agent_versions": {
-            agent_id: meta["package"]["version"]
-            for agent_id, meta in lock["agents"].items()
-            if meta.get("package")
-        },
-        "artifacts": [{"file": path.name, "sha256": sha256(path), "bytes": path.stat().st_size} for path in artifacts],
-    }
-    manifest_path = RELEASE / f"release-manifest-{os_id}-{arch}.json"
-    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-    checksum_path = RELEASE / f"SHA256SUMS-{os_id}-{arch}.txt"
-    checksum_path.write_text("".join(f"{sha256(path)}  {path.name}\n" for path in [*artifacts, manifest_path]), encoding="utf-8")
-    print(artifact)
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/build_release_index.py b/scripts/build_release_index.py
deleted file mode 100755
index 61cb6394..00000000
--- a/scripts/build_release_index.py
+++ /dev/null
@@ -1,418 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import shutil
-from datetime import datetime
-from pathlib import Path, PurePosixPath
-from typing import Any
-from urllib.parse import unquote, urlsplit
-
-
-ROOT = Path(__file__).resolve().parents[1]
-
-
-class ReleaseIndexError(ValueError):
-    pass
-
-
-PLATFORM_LABELS = {"macos": "macOS", "windows": "Windows", "linux": "Linux"}
-ARCH_LABELS = {"arm64": "Apple silicon / ARM64", "x64": "Intel / AMD 64-bit"}
-TARGET_STATUSES = {"available", "verification-pending", "planned", "withdrawn"}
-CLEANROOM_STATUSES = {"verified", "not-recorded", "failed"}
-
-
-def sha256(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for block in iter(lambda: handle.read(1024 * 1024), b""):
-            digest.update(block)
-    return digest.hexdigest()
-
-
-def load_json(path: Path) -> dict[str, Any]:
-    try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        raise ReleaseIndexError(f"Cannot read {path}: {exc}") from exc
-    if not isinstance(value, dict):
-        raise ReleaseIndexError(f"{path} must contain a JSON object")
-    return value
-
-
-def parse_checksums(path: Path) -> dict[str, str]:
-    try:
-        lines = path.read_text(encoding="utf-8").splitlines()
-    except OSError as exc:
-        raise ReleaseIndexError(f"Missing checksum file: {path}") from exc
-    checksums: dict[str, str] = {}
-    for line in lines:
-        if not line.strip():
-            continue
-        parts = line.split(maxsplit=1)
-        if len(parts) != 2:
-            raise ReleaseIndexError(f"Malformed checksum line in {path}: {line}")
-        digest, filename = parts
-        filename = filename.lstrip("* ")
-        if len(digest) != 64 or any(character not in "0123456789abcdef" for character in digest.lower()):
-            raise ReleaseIndexError(f"Malformed SHA-256 in {path}: {digest}")
-        if filename in checksums:
-            raise ReleaseIndexError(f"Duplicate checksum entry in {path}: {filename}")
-        checksums[filename] = digest.lower()
-    return checksums
-
-
-def require_string(value: Any, label: str) -> str:
-    if not isinstance(value, str) or not value.strip():
-        raise ReleaseIndexError(f"{label} must be a non-empty string")
-    return value
-
-
-def require_timestamp(value: Any, label: str) -> str:
-    text = require_string(value, label)
-    try:
-        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
-    except ValueError as exc:
-        raise ReleaseIndexError(f"{label} must be an ISO-8601 timestamp") from exc
-    if parsed.tzinfo is None:
-        raise ReleaseIndexError(f"{label} must include a timezone")
-    return text
-
-
-def validate_manifest(path: Path, release_dir: Path) -> dict[str, Any]:
-    manifest = load_json(path)
-    if manifest.get("schema_version") != 1:
-        raise ReleaseIndexError(f"Unsupported release manifest schema in {path}")
-    for field in ["oneagent_version", "channel", "platform", "arch", "python"]:
-        require_string(manifest.get(field), f"{path.name}.{field}")
-    require_timestamp(manifest.get("built_at"), f"{path.name}.built_at")
-    if not isinstance(manifest.get("unsigned"), bool):
-        raise ReleaseIndexError(f"{path.name}.unsigned must be a boolean")
-    if manifest["channel"] == "technical-preview-unsigned" and not manifest["unsigned"]:
-        raise ReleaseIndexError(f"{path.name} cannot describe a signed technical preview")
-    if manifest["channel"] == "stable" and manifest["unsigned"]:
-        raise ReleaseIndexError(f"{path.name} cannot describe an unsigned Stable build")
-    artifacts = manifest.get("artifacts")
-    if not isinstance(artifacts, list) or not artifacts:
-        raise ReleaseIndexError(f"{path.name}.artifacts must not be empty")
-    if not isinstance(manifest.get("agent_versions"), dict):
-        raise ReleaseIndexError(f"{path.name}.agent_versions must be an object")
-
-    checksum_path = release_dir / f"SHA256SUMS-{manifest['platform']}-{manifest['arch']}.txt"
-    checksums = parse_checksums(checksum_path)
-    manifest_digest = sha256(path)
-    if checksums.get(path.name) != manifest_digest:
-        raise ReleaseIndexError(f"Manifest SHA-256 does not match {checksum_path.name}: {path.name}")
-
-    validated_artifacts: list[dict[str, Any]] = []
-    for item in artifacts:
-        if not isinstance(item, dict):
-            raise ReleaseIndexError(f"{path.name}.artifacts entries must be objects")
-        filename = require_string(item.get("file"), f"{path.name}.artifacts.file")
-        if Path(filename).name != filename:
-            raise ReleaseIndexError(f"Artifact file must be a basename: {filename}")
-        artifact_path = release_dir / filename
-        if not artifact_path.is_file():
-            raise ReleaseIndexError(f"Missing artifact referenced by manifest: {filename}")
-        expected_digest = require_string(item.get("sha256"), f"{filename}.sha256").lower()
-        actual_digest = sha256(artifact_path)
-        if expected_digest != actual_digest:
-            raise ReleaseIndexError(f"Artifact SHA-256 does not match manifest: {filename}")
-        if checksums.get(filename) != actual_digest:
-            raise ReleaseIndexError(f"Artifact SHA-256 does not match {checksum_path.name}: {filename}")
-        if item.get("bytes") != artifact_path.stat().st_size:
-            raise ReleaseIndexError(f"Artifact byte count does not match manifest: {filename}")
-        validated_artifacts.append({"file": filename, "sha256": actual_digest, "bytes": artifact_path.stat().st_size})
-    manifest["artifacts"] = validated_artifacts
-    return manifest
-
-
-def artifact_kind(filename: str) -> str:
-    return "source" if filename.endswith("-source.zip") else "binary"
-
-
-def target_id(platform_id: str, arch: str) -> str:
-    return f"{platform_id}-{arch}"
-
-
-def build_release_index(release_dir: Path, channels_path: Path) -> dict[str, Any]:
-    release_dir = release_dir.resolve()
-    channels_config = load_json(channels_path)
-    if channels_config.get("schema_version") != 1:
-        raise ReleaseIndexError("Unsupported distribution channel schema")
-    product = channels_config.get("product")
-    channels = channels_config.get("channels")
-    if not isinstance(product, dict) or not isinstance(channels, dict):
-        raise ReleaseIndexError("Distribution config requires product and channels objects")
-
-    manifests: dict[tuple[str, str, str], dict[str, Any]] = {}
-    versions: dict[str, set[str]] = {}
-    for path in sorted(release_dir.glob("release-manifest-*.json")):
-        manifest = validate_manifest(path, release_dir)
-        key = (manifest["channel"], manifest["platform"], manifest["arch"])
-        if key in manifests:
-            raise ReleaseIndexError(f"Duplicate release manifest for {'/'.join(key)}")
-        manifests[key] = manifest
-        versions.setdefault(manifest["channel"], set()).add(manifest["oneagent_version"])
-
-    output_channels: list[dict[str, Any]] = []
-    latest: dict[str, str | None] = {}
-    configured_keys: set[tuple[str, str, str]] = set()
-    for channel_id, channel_config in channels.items():
-        if not isinstance(channel_config, dict):
-            raise ReleaseIndexError(f"Channel {channel_id} must be an object")
-        label = require_string(channel_config.get("label"), f"channels.{channel_id}.label")
-        targets = channel_config.get("targets")
-        if not isinstance(targets, list):
-            raise ReleaseIndexError(f"channels.{channel_id}.targets must be an array")
-        channel_versions = versions.get(channel_id, set())
-        if len(channel_versions) > 1:
-            raise ReleaseIndexError(f"Channel {channel_id} contains multiple current versions: {sorted(channel_versions)}")
-        current_version = next(iter(channel_versions), None)
-        latest[channel_id] = current_version
-        output_targets: list[dict[str, Any]] = []
-        channel_unsigned: bool | None = None
-
-        for target in targets:
-            if not isinstance(target, dict):
-                raise ReleaseIndexError(f"Channel {channel_id} target must be an object")
-            platform_id = require_string(target.get("platform"), f"channels.{channel_id}.targets.platform")
-            arch = require_string(target.get("arch"), f"channels.{channel_id}.targets.arch")
-            status = require_string(target.get("status"), f"{channel_id}/{platform_id}/{arch}.status")
-            if status not in TARGET_STATUSES:
-                raise ReleaseIndexError(f"Unsupported target status: {status}")
-            verification = target.get("verification")
-            mirrors = target.get("mirrors")
-            if not isinstance(verification, dict) or not isinstance(mirrors, list):
-                raise ReleaseIndexError(f"{channel_id}/{platform_id}/{arch} requires verification and mirrors")
-            cleanroom = verification.get("cleanroom")
-            if cleanroom not in CLEANROOM_STATUSES:
-                raise ReleaseIndexError(f"Unsupported cleanroom status for {channel_id}/{platform_id}/{arch}")
-            key = (channel_id, platform_id, arch)
-            if key in configured_keys:
-                raise ReleaseIndexError(f"Duplicate distribution target: {channel_id}/{platform_id}/{arch}")
-            configured_keys.add(key)
-            manifest = manifests.get(key)
-
-            validated_mirrors: list[dict[str, Any]] = []
-
-            if status == "available":
-                if manifest is None:
-                    raise ReleaseIndexError(f"Available target has no release manifest: {channel_id}/{platform_id}/{arch}")
-                if verification.get("native_build") is not True:
-                    raise ReleaseIndexError(f"Available target lacks native build evidence: {channel_id}/{platform_id}/{arch}")
-                if cleanroom != "verified" or not verification.get("evidence"):
-                    raise ReleaseIndexError(f"Available target lacks cleanroom evidence: {channel_id}/{platform_id}/{arch}")
-                if not mirrors:
-                    raise ReleaseIndexError(f"Available target has no verified download channel: {channel_id}/{platform_id}/{arch}")
-                mirror_ids: set[str] = set()
-                for mirror in mirrors:
-                    if not isinstance(mirror, dict):
-                        raise ReleaseIndexError(f"Mirror for {channel_id}/{platform_id}/{arch} must be an object")
-                    mirror_id = require_string(mirror.get("id"), "mirror.id")
-                    if mirror_id in mirror_ids:
-                        raise ReleaseIndexError(f"Duplicate mirror id for {channel_id}/{platform_id}/{arch}: {mirror_id}")
-                    mirror_ids.add(mirror_id)
-                    kind = require_string(mirror.get("kind"), "mirror.kind")
-                    if kind not in {"official", "mirror"}:
-                        raise ReleaseIndexError(f"Unsupported mirror kind: {kind}")
-                    url_template = require_string(mirror.get("url"), "mirror.url")
-                    parsed_url = urlsplit(url_template)
-                    if "{file}" not in url_template:
-                        raise ReleaseIndexError(f"Mirror URL must include {{file}}: {mirror_id}")
-                    if parsed_url.scheme not in {"", "https"} or (not parsed_url.scheme and url_template.startswith("/")):
-                        raise ReleaseIndexError(f"Mirror URL must be relative or HTTPS: {mirror_id}")
-                    if ".." in PurePosixPath(unquote(parsed_url.path)).parts:
-                        raise ReleaseIndexError(f"Mirror URL must not escape its download root: {mirror_id}")
-                    if kind == "mirror" and parsed_url.scheme != "https":
-                        raise ReleaseIndexError(f"External mirror must use HTTPS: {mirror_id}")
-                    if kind == "mirror":
-                        audit = mirror.get("audit")
-                        if not isinstance(audit, dict):
-                            raise ReleaseIndexError(f"External mirror requires an audit record: {mirror_id}")
-                        for field in ["uploaded_by", "withdrawal_owner"]:
-                            require_string(audit.get(field), f"mirror.audit.{field}")
-                        for field in ["uploaded_at", "verified_at"]:
-                            require_timestamp(audit.get(field), f"mirror.audit.{field}")
-                        if not isinstance(audit.get("withdrawn"), bool):
-                            raise ReleaseIndexError(f"mirror.audit.withdrawn must be a boolean: {mirror_id}")
-                        if audit["withdrawn"]:
-                            require_timestamp(audit.get("withdrawn_at"), "mirror.audit.withdrawn_at")
-                            continue
-                    validated_mirrors.append(
-                        {
-                            "id": mirror_id,
-                            "label": require_string(mirror.get("label"), "mirror.label"),
-                            "kind": kind,
-                            "url": url_template,
-                            "primary": bool(mirror.get("primary", False)),
-                            "verified_sha256": mirror.get("verified_sha256"),
-                        }
-                    )
-                primary_mirrors = [mirror for mirror in validated_mirrors if mirror["primary"]]
-                if len(primary_mirrors) != 1 or primary_mirrors[0]["kind"] != "official":
-                    raise ReleaseIndexError(
-                        f"Available target requires exactly one primary official channel: {channel_id}/{platform_id}/{arch}"
-                    )
-                if not any(mirror["kind"] == "official" for mirror in validated_mirrors):
-                    raise ReleaseIndexError(f"Available target has no official download channel: {channel_id}/{platform_id}/{arch}")
-
-            artifacts: list[dict[str, Any]] = []
-            if manifest is not None:
-                if current_version != manifest["oneagent_version"]:
-                    raise ReleaseIndexError(f"Manifest version drift for {channel_id}/{platform_id}/{arch}")
-                channel_unsigned = manifest["unsigned"] if channel_unsigned is None else channel_unsigned
-                if channel_unsigned != manifest["unsigned"]:
-                    raise ReleaseIndexError(f"Channel {channel_id} mixes signed and unsigned manifests")
-                for artifact in manifest["artifacts"]:
-                    downloads: list[dict[str, Any]] = []
-                    if status == "available":
-                        for mirror in validated_mirrors:
-                            verified_sha = mirror["verified_sha256"]
-                            if mirror["kind"] == "mirror" and (
-                                not isinstance(verified_sha, str) or verified_sha.lower() != artifact["sha256"]
-                            ):
-                                raise ReleaseIndexError(f"External mirror SHA-256 is not verified for {artifact['file']}")
-                            downloads.append(
-                                {
-                                    "id": mirror["id"],
-                                    "label": mirror["label"],
-                                    "kind": mirror["kind"],
-                                    "url": mirror["url"].replace("{file}", artifact["file"]),
-                                    "primary": mirror["primary"],
-                                }
-                            )
-                    artifacts.append(
-                        {
-                            **artifact,
-                            "kind": artifact_kind(artifact["file"]),
-                            "downloads": downloads,
-                        }
-                    )
-                if status == "available" and not any(item["kind"] == "binary" for item in artifacts):
-                    raise ReleaseIndexError(f"Available target has no binary artifact: {channel_id}/{platform_id}/{arch}")
-
-            output_targets.append(
-                {
-                    "id": target_id(platform_id, arch),
-                    "platform": platform_id,
-                    "platformLabel": PLATFORM_LABELS.get(platform_id, platform_id),
-                    "arch": arch,
-                    "archLabel": ARCH_LABELS.get(arch, arch),
-                    "status": status,
-                    "verification": {
-                        "native_build": bool(verification.get("native_build", False)),
-                        "cleanroom": cleanroom,
-                        "evidence": verification.get("evidence"),
-                    },
-                    "python": manifest.get("python") if manifest else None,
-                    "built_at": manifest.get("built_at") if manifest else None,
-                    "agent_versions": manifest.get("agent_versions", {}) if manifest else {},
-                    "artifacts": artifacts,
-                }
-            )
-
-        published_at = channel_config.get("published_at")
-        if any(target["status"] == "available" for target in output_targets):
-            published_at = require_timestamp(published_at, f"channels.{channel_id}.published_at")
-
-        output_channels.append(
-            {
-                "channel": channel_id,
-                "label": label,
-                "published_at": published_at,
-                "version": current_version,
-                "unsigned": channel_unsigned if channel_unsigned is not None else channel_id != "stable",
-                "status": "available" if any(target["status"] == "available" for target in output_targets) else "unavailable",
-                "targets": output_targets,
-            }
-        )
-
-    unknown = sorted(set(manifests) - configured_keys)
-    if unknown:
-        formatted = ", ".join("/".join(key) for key in unknown)
-        raise ReleaseIndexError(f"Release manifests have no channel target configuration: {formatted}")
-
-    return {
-        "schema_version": 1,
-        "product": product,
-        "latest": latest,
-        "channels": output_channels,
-    }
-
-
-def copy_available_downloads(index: dict[str, Any], release_dir: Path, destination: Path) -> None:
-    reset_destination(destination)
-    for channel in index["channels"]:
-        for target in channel["targets"]:
-            if target["status"] != "available":
-                continue
-            for artifact in target["artifacts"]:
-                source = release_dir / artifact["file"]
-                shutil.copy2(source, destination / artifact["file"])
-
-
-def reset_destination(destination: Path) -> None:
-    destination.mkdir(parents=True, exist_ok=True)
-    for child in destination.iterdir():
-        if child.is_file() or child.is_symlink():
-            child.unlink()
-        else:
-            raise ReleaseIndexError(f"Download destination contains an unexpected directory: {child}")
-
-
-def copy_available_release_assets(index: dict[str, Any], release_dir: Path, destination: Path) -> None:
-    reset_destination(destination)
-    copied: set[str] = set()
-    for channel in index["channels"]:
-        for target in channel["targets"]:
-            if target["status"] != "available":
-                continue
-            metadata = [
-                f"release-manifest-{target['platform']}-{target['arch']}.json",
-                f"SHA256SUMS-{target['platform']}-{target['arch']}.txt",
-            ]
-            for filename in metadata:
-                source = release_dir / filename
-                if not source.is_file():
-                    raise ReleaseIndexError(f"Available release metadata is missing: {filename}")
-                if filename not in copied:
-                    shutil.copy2(source, destination / filename)
-                    copied.add(filename)
-            for artifact in target["artifacts"]:
-                filename = artifact["file"]
-                if filename not in copied:
-                    shutil.copy2(release_dir / filename, destination / filename)
-                    copied.add(filename)
-    (destination / "release-index.json").write_text(
-        json.dumps(index, ensure_ascii=False, indent=2) + "\n",
-        encoding="utf-8",
-    )
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Validate native release manifests and build the public release index")
-    parser.add_argument("--release-dir", type=Path, default=ROOT / "release")
-    parser.add_argument("--channels", type=Path, default=ROOT / "distribution" / "channels.json")
-    parser.add_argument("--output", type=Path, default=ROOT / "site" / "src" / "generated" / "release-index.json")
-    parser.add_argument("--copy-downloads", type=Path)
-    parser.add_argument("--copy-release-assets", type=Path)
-    args = parser.parse_args()
-
-    try:
-        index = build_release_index(args.release_dir, args.channels)
-        args.output.parent.mkdir(parents=True, exist_ok=True)
-        args.output.write_text(json.dumps(index, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-        if args.copy_downloads:
-            copy_available_downloads(index, args.release_dir, args.copy_downloads)
-        if args.copy_release_assets:
-            copy_available_release_assets(index, args.release_dir, args.copy_release_assets)
-    except ReleaseIndexError as exc:
-        raise SystemExit(str(exc)) from exc
-    print(args.output)
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/build_site_catalog.py b/scripts/build_site_catalog.py
deleted file mode 100755
index 8d9f86ef..00000000
--- a/scripts/build_site_catalog.py
+++ /dev/null
@@ -1,143 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from pathlib import Path
-from typing import Any
-from urllib.parse import urlsplit
-
-ROOT = Path(__file__).resolve().parents[1]
-if str(ROOT) not in sys.path:
-    sys.path.insert(0, str(ROOT))
-
-from oneagent.catalog import ADAPTER_PROTOCOLS, AGENT_GROUPS
-
-
-class SiteCatalogError(ValueError):
-    pass
-
-
-PROTOCOL_STATUSES = {"implementation-supported", "release-candidate-required", "verified", "unsupported"}
-
-
-def load_json(path: Path) -> dict[str, Any]:
-    try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        raise SiteCatalogError(f"Cannot read {path}: {exc}") from exc
-    if not isinstance(value, dict):
-        raise SiteCatalogError(f"{path} must contain a JSON object")
-    return value
-
-
-def require_https_url(value: Any, label: str) -> str:
-    if not isinstance(value, str) or not value.strip():
-        raise SiteCatalogError(f"{label} must be a non-empty HTTPS URL")
-    normalized = value.strip()
-    parsed = urlsplit(normalized)
-    if parsed.scheme != "https" or not parsed.netloc:
-        raise SiteCatalogError(f"{label} must use HTTPS")
-    return normalized
-
-
-def build_site_catalog(lock_path: Path, providers_path: Path) -> dict[str, Any]:
-    lock = load_json(lock_path)
-    provider_config = load_json(providers_path)
-    if lock.get("schema_version") != 1 or not isinstance(lock.get("agents"), dict):
-        raise SiteCatalogError("Unsupported Agent lock schema")
-    if provider_config.get("schema_version") != 1 or not isinstance(provider_config.get("providers"), dict):
-        raise SiteCatalogError("Unsupported public Provider schema")
-
-    agents: list[dict[str, Any]] = []
-    for agent_id, meta in lock["agents"].items():
-        if not isinstance(meta, dict):
-            raise SiteCatalogError(f"Agent {agent_id} must be an object")
-        config_mode = meta.get("config_mode")
-        if config_mode not in {"auto", "guide"}:
-            raise SiteCatalogError(f"Agent {agent_id} has unsupported config_mode")
-        package = meta.get("package") if isinstance(meta.get("package"), dict) else None
-        adapter = str(meta.get("config_adapter") or "")
-        managed_install = config_mode == "auto" and package is not None
-        managed_config = config_mode == "auto" and bool(adapter)
-        agents.append(
-            {
-                "id": agent_id,
-                "name": str(meta.get("name") or agent_id),
-                "group": str(meta.get("group") or "other"),
-                "rank": int(meta.get("rank", 99)),
-                "platforms": [str(value) for value in meta.get("platforms", [])],
-                "lockedVersion": str(package.get("version")) if package and package.get("version") else None,
-                "source": str(package.get("source")) if package and package.get("source") else None,
-                "license": str(package.get("license")) if package and package.get("license") else None,
-                "licenseUrl": str(package.get("license_url")) if package and package.get("license_url") else None,
-                "guide": str(meta.get("guide")) if meta.get("guide") else None,
-                "protocol": ADAPTER_PROTOCOLS.get(adapter) if managed_config else None,
-                "support": {
-                    "managedInstall": managed_install,
-                    "officialInstallGuide": config_mode == "guide",
-                    "managedConfig": managed_config,
-                },
-            }
-        )
-    agents.sort(key=lambda agent: (agent["rank"], agent["id"]))
-
-    providers: list[dict[str, Any]] = []
-    for provider_id, meta in provider_config["providers"].items():
-        if not isinstance(meta, dict):
-            raise SiteCatalogError(f"Provider {provider_id} must be an object")
-        relationship = meta.get("relationship", "none")
-        if relationship not in {"none", "referral", "sponsor"}:
-            raise SiteCatalogError(f"Provider {provider_id} has unsupported relationship")
-        if relationship != "none" and (not meta.get("disclosure") or not meta.get("referral_url")):
-            raise SiteCatalogError(f"Provider {provider_id} commercial relationship requires disclosure and referral_url")
-        if relationship == "none" and (meta.get("disclosure") or meta.get("referral_url")):
-            raise SiteCatalogError(f"Provider {provider_id} cannot carry undisclosed commercial fields")
-        protocols = meta.get("protocols", {})
-        if not isinstance(protocols, dict):
-            raise SiteCatalogError(f"Provider {provider_id}.protocols must be an object")
-        for protocol, status in protocols.items():
-            if not isinstance(protocol, str) or status not in PROTOCOL_STATUSES:
-                raise SiteCatalogError(f"Provider {provider_id} has an unsupported protocol status")
-        home = require_https_url(meta.get("home"), f"Provider {provider_id}.home")
-        referral_url = require_https_url(meta.get("referral_url"), f"Provider {provider_id}.referral_url") if relationship != "none" else ""
-        providers.append(
-            {
-                "id": provider_id,
-                "name": str(meta.get("name") or provider_id),
-                "home": home,
-                "relationship": relationship,
-                "disclosure": str(meta.get("disclosure") or ""),
-                "referralUrl": referral_url,
-                "protocols": [{"id": str(key), "status": str(value)} for key, value in protocols.items()],
-                "order": int(meta.get("order", 99)),
-            }
-        )
-    providers.sort(key=lambda provider: (provider["order"], provider["name"]))
-
-    return {
-        "schema_version": 1,
-        "groups": AGENT_GROUPS,
-        "agents": agents,
-        "providers": providers,
-    }
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Project the runtime catalog into public, read-only website data")
-    parser.add_argument("--lock", type=Path, default=ROOT / "agents.lock.json")
-    parser.add_argument("--providers", type=Path, default=ROOT / "distribution" / "providers.json")
-    parser.add_argument("--output", type=Path, default=ROOT / "site" / "src" / "generated" / "catalog.json")
-    args = parser.parse_args()
-    try:
-        catalog = build_site_catalog(args.lock, args.providers)
-    except SiteCatalogError as exc:
-        raise SystemExit(str(exc)) from exc
-    args.output.parent.mkdir(parents=True, exist_ok=True)
-    args.output.write_text(json.dumps(catalog, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-    print(args.output)
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/check_release.py b/scripts/check_release.py
deleted file mode 100755
index 56adab8a..00000000
--- a/scripts/check_release.py
+++ /dev/null
@@ -1,168 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import re
-import zipfile
-from pathlib import Path
-
-
-FORBIDDEN_PARTS = {"node_modules", "output", ".git", "coverage", "test-results", "playwright-report"}
-FORBIDDEN_AGENT_BINARIES = {"codex", "codex.exe", "claude", "claude.exe", "opencode", "opencode.exe", "kilo", "kilo.exe", "aider", "aider.exe"}
-# The release policy forbids CDN and remote-font references in frontend output.
-# Only fetches count: XML namespaces and links in copy are not resource loads.
-REMOTE_ASSET_PATTERNS = [
-    re.compile(rb"""(?:src|href)\s*=\s*["']https?://""", re.IGNORECASE),
-    re.compile(rb"""@import\s+(?:url\()?["']?https?://""", re.IGNORECASE),
-    re.compile(rb"""url\(\s*["']?https?://""", re.IGNORECASE),
-]
-
-SECRET_PATTERNS = [
-    re.compile(rb"sk-[A-Za-z0-9_-]{20,}"),
-    re.compile(rb"Bearer\s+[A-Za-z0-9._-]{24,}", re.IGNORECASE),
-]
-
-
-def sha256(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for block in iter(lambda: handle.read(1024 * 1024), b""):
-            digest.update(block)
-    return digest.hexdigest()
-
-
-def inspect_zip(path: Path) -> list[str]:
-    problems: list[str] = []
-    with zipfile.ZipFile(path) as archive:
-        names = archive.namelist()
-        for name in names:
-            parts = set(Path(name).parts)
-            basename = Path(name).name.lower()
-            if parts & FORBIDDEN_PARTS:
-                problems.append(f"forbidden path in {path.name}: {name}")
-            if name.endswith(".map"):
-                problems.append(f"source map in {path.name}: {name}")
-            if name.endswith((".html", ".css", ".js")) and "/dist/" in f"/{name}":
-                data = archive.read(name)
-                for pattern in REMOTE_ASSET_PATTERNS:
-                    if pattern.search(data):
-                        problems.append(f"remote asset reference in {path.name}: {name}")
-                        break
-            if basename in FORBIDDEN_AGENT_BINARIES:
-                problems.append(f"Agent binary in {path.name}: {name}")
-            if name.endswith((".js", ".css", ".html", ".json", ".md", ".txt", ".toml", ".ps1", ".sh", ".py")):
-                data = archive.read(name)
-                for pattern in SECRET_PATTERNS:
-                    if pattern.search(data):
-                        problems.append(f"possible secret in {path.name}: {name}")
-        required = {"agents.lock.json", "THIRD_PARTY_NOTICES.md"}
-        basenames = {Path(name).name for name in names}
-        for missing in sorted(required - basenames):
-            problems.append(f"missing {missing} in {path.name}")
-    return problems
-
-
-def archive_agent_versions(path: Path) -> dict[str, str] | None:
-    with zipfile.ZipFile(path) as archive:
-        names = [name for name in archive.namelist() if Path(name).name == "agents.lock.json"]
-        if len(names) != 1:
-            return None
-        lock = json.loads(archive.read(names[0]).decode())
-    return {
-        agent_id: str(meta["package"]["version"])
-        for agent_id, meta in lock.get("agents", {}).items()
-        if meta.get("package")
-    }
-
-
-def validate_manifest(path: Path) -> list[str]:
-    problems: list[str] = []
-    try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        return [f"invalid release manifest {path.name}: {exc}"]
-    if data.get("schema_version") != 1:
-        problems.append(f"unsupported release manifest schema: {path.name}")
-    channel = data.get("channel")
-    if channel == "technical-preview-unsigned" and not data.get("unsigned"):
-        problems.append(f"unsigned marker missing: {path.name}")
-    if channel == "stable" and data.get("unsigned"):
-        problems.append(f"Stable manifest cannot be unsigned: {path.name}")
-
-    artifacts = data.get("artifacts")
-    if not isinstance(artifacts, list) or not artifacts:
-        return [*problems, f"artifact list is missing: {path.name}"]
-    expected_versions = data.get("agent_versions")
-    for entry in artifacts:
-        if not isinstance(entry, dict) or not isinstance(entry.get("file"), str):
-            problems.append(f"invalid artifact entry: {path.name}")
-            continue
-        filename = entry["file"]
-        if Path(filename).name != filename:
-            problems.append(f"artifact filename must not contain a path: {filename}")
-            continue
-        artifact = path.parent / filename
-        if not artifact.is_file():
-            problems.append(f"manifest artifact is missing: {filename}")
-            continue
-        if artifact.stat().st_size != entry.get("bytes"):
-            problems.append(f"artifact size mismatch: {filename}")
-        if sha256(artifact) != entry.get("sha256"):
-            problems.append(f"artifact checksum mismatch: {filename}")
-        if channel and not filename.endswith("-source.zip") and channel not in filename:
-            problems.append(f"artifact channel mismatch: {filename}")
-        try:
-            archive_versions = archive_agent_versions(artifact)
-        except (OSError, ValueError, KeyError, json.JSONDecodeError, zipfile.BadZipFile) as exc:
-            problems.append(f"cannot read lock manifest from {filename}: {exc}")
-        else:
-            if archive_versions is None:
-                problems.append(f"lock manifest is missing or duplicated: {filename}")
-            elif archive_versions != expected_versions:
-                problems.append(f"locked Agent versions mismatch: {filename}")
-
-    suffix = path.name.removeprefix("release-manifest-").removesuffix(".json")
-    checksum_path = path.parent / f"SHA256SUMS-{suffix}.txt"
-    if not checksum_path.is_file():
-        problems.append(f"checksum file is missing: {checksum_path.name}")
-        return problems
-    checksums: dict[str, str] = {}
-    for line in checksum_path.read_text(encoding="utf-8").splitlines():
-        match = re.fullmatch(r"([0-9a-f]{64})  ([^/\\]+)", line)
-        if not match:
-            problems.append(f"invalid checksum line in {checksum_path.name}: {line}")
-            continue
-        checksums[match.group(2)] = match.group(1)
-    expected_files = [path, *(path.parent / entry["file"] for entry in artifacts if isinstance(entry, dict) and isinstance(entry.get("file"), str))]
-    for expected in expected_files:
-        if not expected.is_file():
-            continue
-        if checksums.get(expected.name) != sha256(expected):
-            problems.append(f"checksum file mismatch: {expected.name}")
-    return problems
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Validate OneAgent release archives")
-    parser.add_argument("path", type=Path, nargs="?", default=Path("release"))
-    args = parser.parse_args()
-    manifests = list(args.path.glob("release-manifest-*.json"))
-    archives = list(args.path.glob("OneAgent-*.zip"))
-    problems: list[str] = []
-    if not manifests:
-        problems.append("release manifest is missing")
-    if not archives:
-        problems.append("release archive is missing")
-    for manifest in manifests:
-        problems.extend(validate_manifest(manifest))
-    for archive in archives:
-        problems.extend(inspect_zip(archive))
-    if problems:
-        raise SystemExit("\n".join(problems))
-    print(f"release policy checks passed ({len(archives)} archives)")
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/gui.py b/scripts/gui.py
deleted file mode 100755
index 629e0a44..00000000
--- a/scripts/gui.py
+++ /dev/null
@@ -1,20 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-
-if sys.version_info < (3, 12):
-    raise SystemExit("Python 3.12+ is required to run the OneAgent source GUI.")
-
-
-ROOT = Path(__file__).resolve().parents[1]
-if str(ROOT) not in sys.path:
-    sys.path.insert(0, str(ROOT))
-
-from oneagent.server import main
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/install.ps1 b/scripts/install.ps1
deleted file mode 100644
index 9e97ab2b..00000000
--- a/scripts/install.ps1
+++ /dev/null
@@ -1,35 +0,0 @@
-[CmdletBinding()]
-param(
-    [Parameter(ValueFromRemainingArguments = $true)]
-    [string[]] $OneAgentArgs
-)
-
-$ErrorActionPreference = "Stop"
-$RootDir = Split-Path -Parent (Split-Path -Parent $MyInvocation.MyCommand.Path)
-
-$Python = Get-Command python -ErrorAction SilentlyContinue
-if (-not $Python) {
-    $Python = Get-Command py -ErrorAction SilentlyContinue
-}
-if (-not $Python) {
-    Write-Error "Python 3.12+ is required to run the source launcher. Use the self-contained OneAgent package if Python is unavailable."
-    exit 3
-}
-
-$env:PYTHONPATH = if ($env:PYTHONPATH) { "$RootDir;$env:PYTHONPATH" } else { $RootDir }
-if ($Python.Name -eq "py.exe" -or $Python.Name -eq "py") {
-    & $Python.Source -3 -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 12) else 1)"
-    if ($LASTEXITCODE -ne 0) {
-        Write-Error "Python 3.12+ is required to run the source launcher."
-        exit 3
-    }
-    & $Python.Source -3 -m oneagent.cli @OneAgentArgs
-} else {
-    & $Python.Source -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 12) else 1)"
-    if ($LASTEXITCODE -ne 0) {
-        Write-Error "Python 3.12+ is required to run the source launcher."
-        exit 3
-    }
-    & $Python.Source -m oneagent.cli @OneAgentArgs
-}
-exit $LASTEXITCODE
diff --git a/scripts/install.sh b/scripts/install.sh
deleted file mode 100755
index 225343d0..00000000
--- a/scripts/install.sh
+++ /dev/null
@@ -1,17 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-
-if ! command -v python3 >/dev/null 2>&1; then
-  echo "[oneagent] error: Python 3.12+ is required to run the source launcher." >&2
-  exit 3
-fi
-
-if ! python3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 12) else 1)'; then
-  echo "[oneagent] error: Python 3.12+ is required to run the source launcher." >&2
-  exit 3
-fi
-
-export PYTHONPATH="$ROOT_DIR${PYTHONPATH:+:$PYTHONPATH}"
-exec python3 -m oneagent.cli "$@"
diff --git a/scripts/provider_rc_smoke.py b/scripts/provider_rc_smoke.py
deleted file mode 100644
index 4820d37a..00000000
--- a/scripts/provider_rc_smoke.py
+++ /dev/null
@@ -1,186 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import socket
-import sys
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-from urllib.error import HTTPError, URLError
-from urllib.request import Request, urlopen
-
-ROOT = Path(__file__).resolve().parents[1]
-if str(ROOT) not in sys.path:
-    sys.path.insert(0, str(ROOT))
-
-from oneagent.providers import PROTOCOL_ANTHROPIC, openai_base_url, provider_base, provider_config_base
-
-
-FORMAL_RC_PROVIDERS = ("ppio", "novita")
-LOCAL_SMOKE_PROFILES = {
-    "apiproxy": {
-        "openai_base": "https://apiproxy.paigod.work",
-        "anthropic_base": "https://apiproxy.paigod.work",
-        "openai_model": "openai/gpt-5.6-terra",
-        "anthropic_model": "openai/gpt-5.6-terra",
-        "responses_model": "openai/gpt-5.6-terra",
-    }
-}
-
-
-@dataclass(frozen=True)
-class ProviderSmokeConfig:
-    provider: str
-    api_key: str
-    openai_model: str
-    anthropic_model: str
-    responses_model: str
-    openai_base: str = ""
-    anthropic_base: str = ""
-
-
-def _request(label: str, request: Request, timeout: float) -> int:
-    try:
-        with urlopen(request, timeout=timeout) as response:
-            if response.status < 200 or response.status >= 300:
-                raise RuntimeError(f"{label}: unexpected HTTP {response.status}")
-            response.read()
-            return response.status
-    except HTTPError as exc:
-        try:
-            raise RuntimeError(f"{label}: HTTP {exc.code}") from exc
-        finally:
-            exc.close()
-    except (URLError, TimeoutError, socket.timeout) as exc:
-        reason = exc.reason if isinstance(exc, URLError) else exc
-        raise RuntimeError(f"{label}: request failed: {reason}") from exc
-
-
-def _json_request(url: str, api_key: str, body: dict[str, Any], *, anthropic: bool = False) -> Request:
-    headers = {
-        "Authorization": f"Bearer {api_key}",
-        "Content-Type": "application/json",
-    }
-    if anthropic:
-        headers["X-Api-Key"] = api_key
-        headers["Anthropic-Version"] = "2023-06-01"
-    return Request(url, data=json.dumps(body).encode(), method="POST", headers=headers)
-
-
-def smoke_provider(config: ProviderSmokeConfig, *, timeout: float = 30) -> dict[str, int]:
-    if not all([config.api_key, config.openai_model, config.anthropic_model, config.responses_model]):
-        raise RuntimeError(f"{config.provider}: API key and all three protocol model IDs are required")
-    openai = config.openai_base or provider_base(config.provider)
-    anthropic = config.anthropic_base or provider_config_base(config.provider, "", PROTOCOL_ANTHROPIC)
-    v1 = openai_base_url(openai)
-    headers = {"Authorization": f"Bearer {config.api_key}"}
-    results = {
-        "models": _request("models", Request(v1 + "/models", method="GET", headers=headers), timeout),
-        "chat": _request(
-            "chat completions",
-            _json_request(
-                v1 + "/chat/completions",
-                config.api_key,
-                {
-                    "model": config.openai_model,
-                    "messages": [{"role": "user", "content": "Reply with OK."}],
-                    "max_tokens": 8,
-                },
-            ),
-            timeout,
-        ),
-        "responses": _request(
-            "responses",
-            _json_request(
-                v1 + "/responses",
-                config.api_key,
-                {"model": config.responses_model, "input": "Reply with OK.", "max_output_tokens": 8},
-            ),
-            timeout,
-        ),
-        "anthropic": _request(
-            "anthropic messages",
-            _json_request(
-                anthropic.rstrip("/") + "/v1/messages",
-                config.api_key,
-                {
-                    "model": config.anthropic_model,
-                    "messages": [{"role": "user", "content": "Reply with OK."}],
-                    "max_tokens": 8,
-                },
-                anthropic=True,
-            ),
-            timeout,
-        ),
-    }
-    return results
-
-
-def load_api_key_json(path: Path, field: str) -> str:
-    try:
-        payload = json.loads(path.expanduser().read_text(encoding="utf-8"))
-    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
-        raise RuntimeError(f"Cannot read API key JSON file: {exc}") from exc
-    if not isinstance(payload, dict):
-        raise RuntimeError("API key JSON file must contain an object")
-    api_key = payload.get(field)
-    if not isinstance(api_key, str) or not api_key.strip():
-        raise RuntimeError(f"API key JSON field {field!r} is missing or empty")
-    return api_key
-
-
-def config_from_env(provider: str, *, api_key_override: str = "") -> ProviderSmokeConfig:
-    prefix = provider.upper()
-    defaults = LOCAL_SMOKE_PROFILES.get(provider, {})
-    return ProviderSmokeConfig(
-        provider=provider,
-        api_key=api_key_override or os.environ.get(f"ONEAGENT_{prefix}_API_KEY", ""),
-        openai_model=os.environ.get(f"ONEAGENT_{prefix}_OPENAI_MODEL", "")
-        or defaults.get("openai_model", ""),
-        anthropic_model=os.environ.get(f"ONEAGENT_{prefix}_ANTHROPIC_MODEL", "")
-        or defaults.get("anthropic_model", ""),
-        responses_model=os.environ.get(f"ONEAGENT_{prefix}_RESPONSES_MODEL", "")
-        or defaults.get("responses_model", ""),
-        openai_base=os.environ.get(f"ONEAGENT_{prefix}_OPENAI_BASE", "")
-        or defaults.get("openai_base", ""),
-        anthropic_base=os.environ.get(f"ONEAGENT_{prefix}_ANTHROPIC_BASE", "")
-        or defaults.get("anthropic_base", ""),
-    )
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Run low-token Provider protocol checks without logging secrets")
-    parser.add_argument(
-        "--provider",
-        choices=[*FORMAL_RC_PROVIDERS, *LOCAL_SMOKE_PROFILES, "all"],
-        default="all",
-    )
-    parser.add_argument(
-        "--api-key-json",
-        type=Path,
-        help="Read the API key from a local JSON file without putting it on the command line",
-    )
-    parser.add_argument("--api-key-field", default="OPENAI_API_KEY")
-    parser.add_argument("--timeout", type=float, default=30)
-    args = parser.parse_args()
-    if args.api_key_json and args.provider == "all":
-        parser.error("--api-key-json requires one explicit provider")
-    try:
-        api_key_override = load_api_key_json(args.api_key_json, args.api_key_field) if args.api_key_json else ""
-    except RuntimeError as exc:
-        parser.error(str(exc))
-    providers = list(FORMAL_RC_PROVIDERS) if args.provider == "all" else [args.provider]
-    for provider in providers:
-        results = smoke_provider(
-            config_from_env(provider, api_key_override=api_key_override),
-            timeout=args.timeout,
-        )
-        summary = ", ".join(f"{name}=HTTP {status}" for name, status in results.items())
-        print(f"{provider}: {summary}")
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/run_container_cleanroom.sh b/scripts/run_container_cleanroom.sh
deleted file mode 100755
index a5668a72..00000000
--- a/scripts/run_container_cleanroom.sh
+++ /dev/null
@@ -1,174 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-ARTIFACT_DIR="${ONEAGENT_ARTIFACT_DIR:-/artifacts}"
-expected_platform="linux"
-
-if [[ "${ONEAGENT_CLEANROOM_SANITIZED:-0}" != "1" ]]; then
-  exec env -i \
-    PATH="/opt/oneagent-venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" \
-    LANG="C.UTF-8" \
-    LC_ALL="C.UTF-8" \
-    PLAYWRIGHT_BROWSERS_PATH="/ms-playwright" \
-    ONEAGENT_CLEANROOM_SANITIZED="1" \
-    ONEAGENT_DISABLE_BROWSER="1" \
-    ONEAGENT_ARTIFACT_DIR="$ARTIFACT_DIR" \
-    bash "$0"
-fi
-
-mkdir -p "$ARTIFACT_DIR/logs"
-HOME="$(mktemp -d /tmp/oneagent-cleanroom-home.XXXXXX)"
-TMPDIR="$(mktemp -d /tmp/oneagent-cleanroom-tmp.XXXXXX)"
-export HOME TMPDIR
-
-REPORT="$ARTIFACT_DIR/cleanroom-report.json"
-STATUS="failed"
-FAILED_STAGE="initialization"
-
-write_report() {
-  local finished_at
-  local architecture
-  finished_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-  architecture="$(uname -m)"
-  printf '{\n  "schemaVersion": 1,\n  "environment": "docker-cleanroom",\n  "platform": "%s",\n  "arch": "%s",\n  "network": "none",\n  "status": "%s",\n  "failedStage": "%s",\n  "finishedAt": "%s"\n}\n' \
-    "$expected_platform" "$architecture" "$STATUS" "$FAILED_STAGE" "$finished_at" > "$REPORT"
-}
-
-collect_artifacts() {
-  if [[ -f "$ROOT_DIR/build/coverage/coverage.json" ]]; then
-    cp -f "$ROOT_DIR/build/coverage/coverage.json" "$ARTIFACT_DIR/coverage-python.json" || true
-  fi
-  if [[ -f "$ROOT_DIR/frontend/coverage/coverage-summary.json" ]]; then
-    cp -f "$ROOT_DIR/frontend/coverage/coverage-summary.json" "$ARTIFACT_DIR/coverage-react.json" || true
-  fi
-  if [[ -d "$ROOT_DIR/frontend/test-results" ]]; then
-    rm -rf "$ARTIFACT_DIR/playwright-test-results"
-    cp -R "$ROOT_DIR/frontend/test-results" "$ARTIFACT_DIR/playwright-test-results" || true
-  fi
-  if [[ -d "$ROOT_DIR/frontend/playwright-report" ]]; then
-    rm -rf "$ARTIFACT_DIR/playwright-report"
-    cp -R "$ROOT_DIR/frontend/playwright-report" "$ARTIFACT_DIR/playwright-report" || true
-  fi
-}
-
-finish() {
-  local exit_code=$?
-  trap - EXIT
-  collect_artifacts
-  write_report
-  rm -rf "$HOME" "$TMPDIR"
-  exit "$exit_code"
-}
-trap finish EXIT
-
-run_stage() {
-  local name="$1"
-  shift
-  FAILED_STAGE="$name"
-  echo "==> $name"
-  "$@" \
-    > >(tee "$ARTIFACT_DIR/logs/$name.stdout.log") \
-    2> >(tee "$ARTIFACT_DIR/logs/$name.stderr.log" >&2)
-}
-
-assert_clean_environment() {
-  [[ "$(uname -s)" == "Linux" ]] || {
-    echo "Docker cleanroom must report the real Linux platform." >&2
-    return 1
-  }
-  [[ "$(id -u)" != "0" ]] || {
-    echo "Docker cleanroom must run as a non-root user." >&2
-    return 1
-  }
-
-  python3.12 - <<'PY'
-import os
-
-markers = ("KEY", "TOKEN", "SECRET", "PASSWORD")
-leaked = sorted(name for name in os.environ if any(marker in name.upper() for marker in markers))
-if leaked:
-    raise SystemExit(f"secret-shaped environment variables remain: {', '.join(leaked)}")
-PY
-
-  local command_name
-  for command_name in codex claude opencode kilo aider uv; do
-    if command -v "$command_name" >/dev/null 2>&1; then
-      echo "unexpected preinstalled command: $command_name" >&2
-      return 1
-    fi
-  done
-
-  local relative
-  for relative in .codex .claude .config/opencode .config/kilo .oneagent .aider.conf.yml; do
-    if [[ -e "$HOME/$relative" ]]; then
-      echo "unexpected user configuration: $HOME/$relative" >&2
-      return 1
-    fi
-  done
-}
-
-scan_release_policy() {
-  if find "$ROOT_DIR/frontend/dist" -type f -name '*.map' -print -quit | grep -q .; then
-    echo "frontend build contains source maps" >&2
-    return 1
-  fi
-  if rg -n 'https?://(fonts\.|cdn\.|unpkg\.|jsdelivr\.)' \
-    "$ROOT_DIR/frontend/dist"; then
-    echo "frontend build contains a forbidden remote asset" >&2
-    return 1
-  fi
-  if rg -n 'shell\s*=\s*True' "$ROOT_DIR/oneagent" "$ROOT_DIR/scripts"; then
-    echo "Python subprocess shell invocation is forbidden" >&2
-    return 1
-  fi
-  if rg -n 'curl[^|\n]*\|\s*(bash|sh)' \
-    "$ROOT_DIR/oneagent" "$ROOT_DIR/scripts" "$ROOT_DIR/frontend/src"; then
-    echo "executable curl-pipe installation is forbidden" >&2
-    return 1
-  fi
-  if rg -n -o 'sk-[A-Za-z0-9_-]{20,}|Bearer[[:space:]]+[A-Za-z0-9._-]{24,}' \
-    --glob '!frontend/node_modules/**' \
-    --glob '!build/**' \
-    --glob '!release/**' \
-    --glob '!output/**' \
-    "$ROOT_DIR"; then
-    echo "possible secret found in source or generated assets" >&2
-    return 1
-  fi
-  if rg -n -o 'sk-[A-Za-z0-9_-]{20,}|Bearer[[:space:]]+[A-Za-z0-9._-]{24,}' \
-    "$ARTIFACT_DIR"; then
-    echo "possible secret found in cleanroom artifacts" >&2
-    return 1
-  fi
-}
-
-cd "$ROOT_DIR"
-run_stage environment assert_clean_environment
-
-mkdir -p build/coverage
-run_stage python-contracts bash -c '
-  coverage erase
-  coverage run --branch -m unittest \
-    tests.test_core tests.test_cli tests.test_server \
-    tests.test_release_policy tests.test_edge_cases tests.test_rc_scripts
-  coverage report --fail-under=85
-  coverage json
-  python3.12 -c '\''import json; summary = json.load(open("build/coverage/coverage.json", encoding="utf-8"))["files"]["oneagent/installer.py"]["summary"]; assert summary["percent_branches_covered"] == 100 and summary["num_partial_branches"] == 0, summary'\''
-'
-
-run_stage bash-compatibility bash tests/install_test.sh
-run_stage existing-config bash tests/existing_config_test.sh
-run_stage gui-smoke python3.12 tests/gui_smoke_test.py
-
-run_stage react-coverage bash -c 'cd frontend && npm run test:coverage'
-
-run_stage react-build bash -c 'cd frontend && npm run build'
-run_stage browser-e2e bash -c 'cd frontend && npm run e2e'
-
-collect_artifacts
-run_stage policy-scan scan_release_policy
-
-STATUS="passed"
-FAILED_STAGE=""
-echo "Docker Linux cleanroom passed."
diff --git a/scripts/stage_resources.py b/scripts/stage_resources.py
deleted file mode 100644
index ebf70b39..00000000
--- a/scripts/stage_resources.py
+++ /dev/null
@@ -1,54 +0,0 @@
-#!/usr/bin/env python3
-"""Copy the runtime resources a wheel must carry into the package directory.
-
-`agents.lock.json` and the built frontend live at the repository root because
-both the source checkout and the PyInstaller bundle read them from there. A
-wheel only carries files inside the package directory, so without this step an
-installed OneAgent starts and fails with "Cannot load Agent lock manifest".
-
-Deliberately free of any setuptools import: `setup.py` drives this from a
-build_py hook, but the tests must be able to exercise it on a bare Python 3.12,
-which no longer ships setuptools.
-"""
-
-from __future__ import annotations
-
-import shutil
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[1]
-RESOURCES = ROOT / "oneagent" / "_resources"
-
-
-def prune_stale_build_output(build_lib: Path | str) -> Path | None:
-    """Drop a previously copied _resources tree from setuptools' build dir.
-
-    build_py copies package data into build/lib but never prunes entries that
-    changed or disappeared, and build/ survives between builds. Left alone, a
-    stale copy is packaged in preference to whatever staging just produced --
-    including an outdated agents.lock.json, which would silently undo the
-    version locking the release policy depends on.
-    """
-    stale = Path(build_lib) / "oneagent" / "_resources"
-    if stale.exists():
-        shutil.rmtree(stale)
-        return stale
-    return None
-
-
-def stage_resources(root: Path | None = None) -> Path:
-    """Refresh <package>/_resources and return it."""
-    base = root or ROOT
-    resources = base / "oneagent" / "_resources"
-    if resources.exists():
-        shutil.rmtree(resources)
-    resources.mkdir(parents=True)
-    shutil.copy2(base / "agents.lock.json", resources / "agents.lock.json")
-    frontend_dist = base / "frontend" / "dist"
-    if frontend_dist.is_dir():
-        shutil.copytree(frontend_dist, resources / "frontend" / "dist")
-    return resources
-
-
-if __name__ == "__main__":
-    print(stage_resources())
diff --git a/scripts/test_docker_cleanroom.sh b/scripts/test_docker_cleanroom.sh
deleted file mode 100755
index d633ff17..00000000
--- a/scripts/test_docker_cleanroom.sh
+++ /dev/null
@@ -1,40 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-IMAGE="${ONEAGENT_CLEANROOM_IMAGE:-oneagent-cleanroom:0.2.0-dev}"
-ARTIFACT_DIR="$ROOT_DIR/build/docker-cleanroom"
-
-command -v docker >/dev/null 2>&1 || {
-  echo "Docker is required to run the Linux cleanroom." >&2
-  exit 2
-}
-
-rm -rf "$ARTIFACT_DIR"
-mkdir -p "$ARTIFACT_DIR"
-chmod 0777 "$ARTIFACT_DIR"
-
-# The daemon rejects --cpus above its own CPU count, and the daemon may have
-# fewer CPUs than the host (Docker Desktop VM, 2-vCPU CI runners). Ask the
-# daemon rather than the host, and cap the request at what it reports.
-CLEANROOM_CPUS="${ONEAGENT_CLEANROOM_CPUS:-}"
-if [ -z "$CLEANROOM_CPUS" ]; then
-  DAEMON_CPUS="$(docker info --format '{{.NCPU}}' 2>/dev/null || true)"
-  case "$DAEMON_CPUS" in
-    ''|*[!0-9]*) DAEMON_CPUS=2 ;;
-  esac
-  if [ "$DAEMON_CPUS" -lt 4 ]; then
-    CLEANROOM_CPUS="$DAEMON_CPUS"
-  else
-    CLEANROOM_CPUS=4
-  fi
-fi
-
-docker build --progress plain -f "$ROOT_DIR/Dockerfile.test" -t "$IMAGE" "$ROOT_DIR" \
-  2>&1 | tee "$ARTIFACT_DIR/docker-build.log"
-docker run --rm --init --network none --shm-size=1g \
-  --memory=4g --cpus="$CLEANROOM_CPUS" \
-  -v "$ARTIFACT_DIR:/artifacts" \
-  "$IMAGE" 2>&1 | tee "$ARTIFACT_DIR/docker-run.log"
-
-echo "Linux cleanroom artifacts: $ARTIFACT_DIR"
diff --git a/scripts/verify_locked_agents.py b/scripts/verify_locked_agents.py
deleted file mode 100644
index e30ba763..00000000
--- a/scripts/verify_locked_agents.py
+++ /dev/null
@@ -1,131 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import os
-import shutil
-import tempfile
-from pathlib import Path
-
-from oneagent.catalog import current_platform, load_manifest
-from oneagent.installer import InstallOptions, Runtime, install_many, installed_version
-
-
-SECRET_ENV_MARKERS = ("KEY", "TOKEN", "SECRET", "PASSWORD")
-
-
-def create_isolated_runtime(
-    root: Path,
-    *,
-    os_id: str | None = None,
-    base_env: dict[str, str] | None = None,
-) -> Runtime:
-    platform_id = os_id or current_platform()["os"]
-    cleanroom = root.absolute()
-    home = cleanroom / "home"
-    npm_prefix = cleanroom / "npm-prefix"
-    npm_bin = npm_prefix if platform_id == "windows" else npm_prefix / "bin"
-    uv_tool_dir = cleanroom / "uv-tools"
-    uv_bin = cleanroom / "uv-bin"
-    cache = cleanroom / "cache"
-    temp = cleanroom / "tmp"
-    for path in (home, npm_prefix, npm_bin, uv_tool_dir, uv_bin, cache, temp):
-        path.mkdir(parents=True, exist_ok=True)
-
-    original = dict(base_env if base_env is not None else os.environ)
-    env = {
-        name: value
-        for name, value in original.items()
-        if not any(marker in name.upper() for marker in SECRET_ENV_MARKERS)
-    }
-    env.pop("UV_CONFIG_FILE", None)
-    env.pop("PIP_CONFIG_FILE", None)
-    original_path = env.get("PATH", "")
-    isolated_path = os.pathsep.join(
-        part for part in (str(uv_bin), str(npm_bin), original_path) if part
-    )
-    env.update(
-        {
-            "HOME": str(home),
-            "USERPROFILE": str(home),
-            "ONEAGENT_HOME": str(home),
-            "NPM_CONFIG_PREFIX": str(npm_prefix),
-            "NPM_CONFIG_CACHE": str(cache / "npm"),
-            "NPM_CONFIG_USERCONFIG": str(cleanroom / "npmrc"),
-            "UV_TOOL_DIR": str(uv_tool_dir),
-            "UV_TOOL_BIN_DIR": str(uv_bin),
-            "UV_CACHE_DIR": str(cache / "uv"),
-            "XDG_CONFIG_HOME": str(cleanroom / "xdg-config"),
-            "XDG_CACHE_HOME": str(cache / "xdg"),
-            "APPDATA": str(cleanroom / "appdata"),
-            "LOCALAPPDATA": str(cleanroom / "local-appdata"),
-            "TMPDIR": str(temp),
-            "TEMP": str(temp),
-            "TMP": str(temp),
-            "PATH": isolated_path,
-        }
-    )
-
-    manifest = load_manifest()
-    agent_commands = {
-        str(meta["command"])
-        for meta in manifest["agents"].values()
-        if meta.get("config_mode") == "auto" and meta.get("command")
-    }
-    isolated_roots = (npm_prefix.resolve(), uv_bin.resolve(), uv_tool_dir.resolve())
-
-    def isolated_which(command: str) -> str | None:
-        candidate = shutil.which(command, path=env["PATH"])
-        if not candidate or command not in agent_commands:
-            return candidate
-        resolved = Path(candidate).resolve()
-        if any(resolved == root_path or root_path in resolved.parents for root_path in isolated_roots):
-            return candidate
-        return None
-
-    return Runtime.create(home=home, os_id=platform_id, which=isolated_which, env=env)
-
-
-def _verify(runtime: Runtime) -> dict[str, str]:
-    manifest = load_manifest()
-    verified: dict[str, str] = {}
-    for agent_id, meta in manifest["agents"].items():
-        if meta.get("config_mode") != "auto":
-            continue
-        result = install_many(
-            InstallOptions(
-                agents=[agent_id],
-                configure=False,
-                install_agent=True,
-                check_agent_only=True,
-                locked_version=True,
-                home=runtime.home,
-                os_id=runtime.os_id,
-                timeout=900,
-            ),
-            runtime,
-        )
-        if not result["ok"]:
-            message = result["results"][0].get("message") or "installation failed"
-            raise RuntimeError(f"{agent_id}: {message}")
-        actual = installed_version(runtime, meta)
-        expected = str(meta["package"]["version"])
-        if actual != expected:
-            raise RuntimeError(f"{agent_id}: expected {expected}, got {actual or 'unavailable'}")
-        verified[agent_id] = actual
-    return verified
-
-
-def verify_locked_agents(runtime: Runtime | None = None) -> dict[str, str]:
-    if runtime is not None:
-        return _verify(runtime)
-    with tempfile.TemporaryDirectory() as tmp:
-        return _verify(create_isolated_runtime(Path(tmp)))
-
-
-def main() -> None:
-    for agent_id, version in verify_locked_agents().items():
-        print(f"{agent_id}: {version}")
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/verify_wheel.py b/scripts/verify_wheel.py
deleted file mode 100644
index ed628495..00000000
--- a/scripts/verify_wheel.py
+++ /dev/null
@@ -1,131 +0,0 @@
-#!/usr/bin/env python3
-"""Build the wheel, install it into a throwaway virtualenv and exercise it.
-
-The wheel is the only artifact whose resources are staged rather than read from
-the repository, so a packaging mistake is invisible to every other check: the
-source checkout and the PyInstaller bundle keep working while `pip install`
-produces something that fails on first run with "Cannot load Agent lock
-manifest". This runs the installed console script from a directory outside the
-repository so nothing can fall back to the working copy.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import subprocess
-import sys
-import tempfile
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[1]
-
-
-def venv_bin(env_dir: Path, name: str) -> Path:
-    if sys.platform == "win32":
-        return env_dir / "Scripts" / f"{name}.exe"
-    return env_dir / "bin" / name
-
-
-def build_wheel(destination: Path) -> Path:
-    destination.mkdir(parents=True, exist_ok=True)
-    # --no-cache-dir is load-bearing: pip happily serves a previously built
-    # wheel for an unchanged version, so without it this check silently
-    # validates a stale artifact instead of the current tree.
-    subprocess.run(
-        [
-            sys.executable,
-            "-m",
-            "pip",
-            "wheel",
-            str(ROOT),
-            "--no-deps",
-            "--no-cache-dir",
-            "-w",
-            str(destination),
-        ],
-        check=True,
-        cwd=ROOT,
-    )
-    wheels = sorted(destination.glob("oneagent_launcher-*.whl"))
-    if not wheels:
-        raise SystemExit(f"no wheel produced in {destination}")
-    return wheels[-1]
-
-
-def verify_wheel(wheel: Path) -> None:
-    with tempfile.TemporaryDirectory() as tmp:
-        workspace = Path(tmp).resolve()
-        env_dir = workspace / "venv"
-        # Spawned rather than venv.EnvBuilder(): relocatable CPython builds
-        # (uv, python-build-standalone) resolve sys._base_executable
-        # incorrectly in-process and their ensurepip then fails to start.
-        subprocess.run([sys.executable, "-m", "venv", str(env_dir)], check=True)
-        python = venv_bin(env_dir, "python")
-        subprocess.run(
-            [str(python), "-m", "pip", "install", "--quiet", "--disable-pip-version-check", str(wheel)],
-            check=True,
-        )
-
-        # Resources must resolve to the staged copy inside site-packages.
-        probe = subprocess.run(
-            [
-                str(python),
-                "-c",
-                "import json;"
-                " from oneagent.catalog import resource_root, agent_catalog;"
-                " from oneagent.server import static_root;"
-                " root = resource_root();"
-                " print(json.dumps({"
-                "  'manifest': (root / 'agents.lock.json').is_file(),"
-                "  'agents': len(agent_catalog()),"
-                "  'frontend': (static_root() / 'index.html').is_file(),"
-                " }))",
-            ],
-            check=True,
-            capture_output=True,
-            text=True,
-            cwd=workspace,
-        )
-        state = json.loads(probe.stdout.strip().splitlines()[-1])
-        if not state["manifest"]:
-            raise SystemExit("installed wheel cannot find agents.lock.json")
-        if state["agents"] < 1:
-            raise SystemExit("installed wheel loaded an empty Agent catalog")
-        if not state["frontend"]:
-            raise SystemExit("installed wheel does not carry the built frontend")
-
-        # The console script must run outside the repository.
-        result = subprocess.run(
-            [
-                str(venv_bin(env_dir, "oneagent")),
-                "--agent",
-                "openclaw",
-                "--check-agent-only",
-                "--json",
-                "--home",
-                str(workspace / "home"),
-            ],
-            check=True,
-            capture_output=True,
-            text=True,
-            cwd=workspace,
-        )
-        payload = json.loads(result.stdout.strip().splitlines()[-1])
-        if not payload.get("ok"):
-            raise SystemExit(f"installed CLI reported failure: {payload}")
-
-        print(f"wheel verified: {state['agents']} agents, frontend bundled, CLI ok")
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Build and smoke-test the OneAgent wheel")
-    parser.add_argument("--wheel", type=Path, help="Verify an existing wheel instead of building one")
-    args = parser.parse_args()
-    with tempfile.TemporaryDirectory() as tmp:
-        wheel = args.wheel or build_wheel(Path(tmp) / "dist")
-        verify_wheel(wheel)
-
-
-if __name__ == "__main__":
-    main()
diff --git a/setup.py b/setup.py
deleted file mode 100644
index 1ce695f0..00000000
--- a/setup.py
+++ /dev/null
@@ -1,35 +0,0 @@
-"""Stage runtime resources into the package before a wheel or sdist is built.
-
-The copying itself lives in scripts/stage_resources.py so the tests can
-exercise it without setuptools installed; this module only wires it into the
-build. Loaded by explicit path rather than a plain import so it does not depend
-on the repository root being on sys.path during a PEP 517 build.
-"""
-
-from __future__ import annotations
-
-import importlib.util
-from pathlib import Path
-
-from setuptools import setup
-from setuptools.command.build_py import build_py
-
-ROOT = Path(__file__).resolve().parent
-_spec = importlib.util.spec_from_file_location(
-    "oneagent_stage_resources", ROOT / "scripts" / "stage_resources.py"
-)
-_module = importlib.util.module_from_spec(_spec)
-_spec.loader.exec_module(_module)
-stage_resources = _module.stage_resources
-prune_stale_build_output = _module.prune_stale_build_output
-
-
-class BuildPyWithResources(build_py):
-    def run(self) -> None:
-        stage_resources(ROOT)
-        prune_stale_build_output(self.build_lib)
-        super().run()
-
-
-if __name__ == "__main__":
-    setup(cmdclass={"build_py": BuildPyWithResources})
diff --git a/site/astro.config.mjs b/site/astro.config.mjs
index 48c9e724..c0f90fe1 100644
--- a/site/astro.config.mjs
+++ b/site/astro.config.mjs
@@ -9,6 +9,13 @@ export default defineConfig({
   site,
   base,
   output: "static",
+  // Chinese stays unprefixed so every published URL keeps working; English is
+  // additive under /en/.
+  i18n: {
+    defaultLocale: "zh-CN",
+    locales: ["zh-CN", "en"],
+    routing: { prefixDefaultLocale: false },
+  },
   integrations: [sitemap()],
   build: {
     assets: "_assets",
diff --git a/site/e2e/site.spec.ts b/site/e2e/site.spec.ts
index a9c33ed6..e228fac1 100644
--- a/site/e2e/site.spec.ts
+++ b/site/e2e/site.spec.ts
@@ -1,7 +1,14 @@
-import { test, expect } from "@playwright/test";
+import { test, expect, type Page } from "@playwright/test";
 import axe from "axe-core";
 
-const criticalPages = ["/", "/downloads/", "/agents/", "/security/"];
+const criticalPages = ["/", "/explore/", "/downloads/", "/agents/", "/security/"];
+
+/* Mirrors translatedRoutes in src/i18n/index.ts. It cannot be imported here:
+   that module reads import.meta.env.BASE_URL, which only exists under Vite, and
+   Playwright runs this file in plain Node. The englishPages list below is the
+   guard — every route named here has to have an /en/ page that gets audited, so
+   the two drifting apart fails rather than going unnoticed. */
+const translatedRoutes = ["", "downloads/", "quickstart/", "explore/", "security/"];
 
 test("critical pages fit the viewport without horizontal scrolling", async ({ page }) => {
   for (const path of criticalPages) {
@@ -14,30 +21,374 @@ test("critical pages fit the viewport without horizontal scrolling", async ({ pa
   }
 });
 
-test("home states the product boundary and current channel", async ({ page }) => {
+test("home presents one activation entry without claiming a real scan", async ({ page }) => {
   await page.goto("/");
   await expect(page.getByRole("heading", { level: 1 })).toContainText("激活你的 AI 开发环境");
-  await expect(page.getByRole("link", { name: "下载 OneAgent" })).toBeVisible();
-  await expect(page.getByText("自己的 Key", { exact: true })).toBeVisible();
+  await expect(page.locator(".hero-actions").getByRole("button", { name: "开始激活演示" })).toBeVisible();
+  await expect(page.locator(".hero-actions").getByRole("link")).toHaveCount(0);
+  /* The console used to sit at idle until clicked. It now plays itself once it
+     scrolls into view, so the successor guarantee is that the page drives the
+     demo — the button stays as the replay and takeover entry. Scrolled here
+     explicitly because whether the console starts on screen varies by viewport,
+     and this test is not the one about the trigger threshold. */
+  const console = page.locator("#activation-console");
+  await console.scrollIntoViewIfNeeded();
+  await expect(console).toHaveAttribute("data-autoplaying", "true");
+  await expect(page.getByText("示例环境", { exact: true }).first()).toBeVisible();
+  await expect(page.getByText("不访问设备", { exact: true })).toBeVisible();
+  await expect(page.locator('input[type="password"], input[name*="key" i]')).toHaveCount(0);
   await expect(page.locator(".hero-note")).toContainText("未签名技术预览版");
 });
 
-test("download center recommends an available artifact but keeps manual choices", async ({ page, request }) => {
-  const index = await (await request.get("/release-index.json")).json();
-  const preview = index.channels.find((channel: { channel: string }) => channel.channel === "technical-preview-unsigned");
-  const mac = preview.targets.find((target: { id: string }) => target.id === "macos-arm64");
-  const expectedSha = mac.artifacts[0].sha256;
+test("activation demo reaches Ready only for a supported managed combination", async ({ page }) => {
+  const fetches: string[] = [];
+  page.on("request", (request) => {
+    if (["fetch", "xhr"].includes(request.resourceType())) fetches.push(request.url());
+  });
+  await page.goto("/");
+  const console = page.locator("#activation-console");
+  await page.getByRole("button", { name: "开始激活演示" }).click();
+  await expect(console).toHaveAttribute("data-phase", "agent");
+  await console.getByRole("button", { name: /Claude Code/ }).click();
+  await expect(console).toHaveAttribute("data-phase", "mode");
+  await console.getByRole("button", { name: /配置模型服务/ }).click();
+  await expect(console).toHaveAttribute("data-phase", "provider");
+  await console.getByRole("button", { name: /PPIO/ }).click();
+  await console.getByRole("button", { name: "验证示例连接" }).click();
+  await expect(console).toHaveAttribute("data-phase", "model");
+  await console.getByRole("button", { name: "deepseek/deepseek-v3" }).click();
+  await console.getByRole("button", { name: "确认激活" }).click();
+  await expect(console).toHaveAttribute("data-phase", "ready");
+  await expect(console.getByRole("heading", { name: "示例环境已 Ready" })).toBeVisible();
+  await expect(console.getByRole("link", { name: "下载 OneAgent" })).toBeVisible();
+  await expect(console.getByRole("link", { name: "打开完整配置目录" })).toBeVisible();
+  await page.addScriptTag({ content: axe.source });
+  const result = await page.evaluate(async () => {
+    const axeApi = (window as typeof window & { axe: typeof axe }).axe;
+    return axeApi.run(document.querySelector("#activation-console")!, {
+      runOnly: { type: "tag", values: ["wcag2a", "wcag2aa"] },
+    });
+  });
+  const serious = result.violations.filter(
+    (violation) => violation.impact === "serious" || violation.impact === "critical",
+  );
+  expect(serious, JSON.stringify(serious, null, 2)).toEqual([]);
+  expect(fetches, "the public demo must not call a local or remote activation API").toEqual([]);
+});
+
+test("activation demo preserves guide-only and preview-gate boundaries", async ({ page }) => {
+  await page.goto("/");
+  const console = page.locator("#activation-console");
+
+  await page.getByRole("button", { name: "开始激活演示" }).click();
+  await expect(console).toHaveAttribute("data-phase", "agent");
+  await console.getByRole("button", { name: /Cursor/ }).click();
+  await expect(console).toHaveAttribute("data-phase", "guide-only");
+  await expect(console.getByRole("heading", { name: "转入官方设置" })).toBeVisible();
+  await expect(console.getByRole("link", { name: "下载 OneAgent" })).toBeHidden();
+
+  await console.getByRole("button", { name: "重置演示" }).click();
+  await page.getByRole("button", { name: "开始激活演示" }).click();
+  await expect(console).toHaveAttribute("data-phase", "agent");
+  await console.getByRole("button", { name: /Codex/ }).click();
+  await console.getByRole("button", { name: /配置模型服务/ }).click();
+  await console.getByRole("button", { name: /PPIO/ }).click();
+  await console.getByRole("button", { name: "验证示例连接" }).click();
+  await expect(console).toHaveAttribute("data-phase", "preview-gate");
+  await expect(console.getByRole("heading", { name: "仍需通过发布门禁" })).toBeVisible();
+  await expect(console.getByRole("link", { name: "下载 OneAgent" })).toBeHidden();
+  await expect(console.getByRole("link", { name: "发行政策" })).toBeVisible();
+});
+
+// The custom endpoint is the demo's only typed input, and its whole point is
+// that the browser applies the same rules as oneagent/providers.py. A field that
+// accepted anything would teach visitors an endpoint works when the app rejects it.
+test("activation demo validates a custom endpoint the way the app does", async ({ page }) => {
+  const fetches: string[] = [];
+  page.on("request", (request) => {
+    if (["fetch", "xhr"].includes(request.resourceType())) fetches.push(request.url());
+  });
+  await page.goto("/");
+  const console = page.locator("#activation-console");
+  await page.getByRole("button", { name: "开始激活演示" }).click();
+  await console.getByRole("button", { name: /Claude Code/ }).click();
+  await console.getByRole("button", { name: /配置模型服务/ }).click();
+  await console.getByRole("button", { name: /自定义端点/ }).click();
+
+  const url = console.getByLabel("Base URL");
+  const verify = console.getByRole("button", { name: "验证示例连接" });
+  await expect(url).toBeVisible();
+  await expect(verify).toBeDisabled();
+
+  for (const [value, message] of [
+    ["ftp://api.example.com", "需要以 http:// 或 https:// 开头。"],
+    ["https://user:secret@api.example.com", "请从地址中去掉用户名或密码。"],
+  ]) {
+    await url.fill(value);
+    await expect(console.locator("[data-custom-hint]")).toHaveText(message);
+    await expect(url).toHaveAttribute("aria-invalid", "true");
+    await expect(verify, `${value} must not be verifiable`).toBeDisabled();
+  }
+
+  await url.fill("https://api.example.com/openai");
+  await expect(console.locator("[data-custom-hint]")).toHaveText("端点可用");
+  await expect(verify).toBeEnabled();
+  await verify.click();
+
+  // A custom endpoint publishes no catalog, so the demo shows the app's real
+  // recovery — type the id — rather than inventing a discovered list.
+  await expect(console).toHaveAttribute("data-phase", "model");
+  await expect(console.locator("[data-model-grid]")).toBeHidden();
+  await console.getByLabel("模型 ID").fill("deepseek/deepseek-v3");
+  await console.getByRole("button", { name: "确认激活" }).click();
+  await expect(console).toHaveAttribute("data-phase", "ready");
+  await expect(console.locator("[data-result-provider]")).toHaveText("api.example.com");
+  expect(fetches, "typing an endpoint must not make the page call it").toEqual([]);
+});
+
+// Reusing an existing account is a real branch in the product's ConfigModePage,
+// and it exists precisely because no new credential is introduced — so the demo
+// must not walk it through provider and model steps it genuinely skips.
+test("activation demo skips provider and model for an existing account", async ({ page }) => {
+  await page.goto("/");
+  const console = page.locator("#activation-console");
+  await page.getByRole("button", { name: "开始激活演示" }).click();
+  await console.getByRole("button", { name: /Claude Code/ }).click();
+  await expect(console).toHaveAttribute("data-phase", "mode");
+  await console.getByRole("button", { name: /使用已有账号或配置/ }).click();
+
+  await expect(console).toHaveAttribute("data-phase", "ready");
+  await expect(console.getByRole("heading", { name: "保留现有账号" })).toBeVisible();
+  await expect(console.locator(".activation-steps li.is-skipped")).toHaveCount(2);
+  await expect(console.locator("[data-result-provider]")).toHaveText("已跳过");
+  await expect(console.locator("[data-log]")).toContainText("Provider 与模型步骤已跳过");
+});
+
+test("activation demo keeps a complete event history under reduced motion", async ({ page }) => {
+  await page.emulateMedia({ reducedMotion: "reduce" });
+  await page.goto("/");
+  const console = page.locator("#activation-console");
+  /* Advancing the interface on its own is motion, so reduced motion means the
+     console waits to be asked. That is also what keeps the rest of this test
+     valid: nothing has moved off idle before the first click. */
+  await console.scrollIntoViewIfNeeded();
+  await expect(console).toHaveAttribute("data-phase", "idle");
+  await expect(console).not.toHaveAttribute("data-autoplaying", "true");
+  await page.getByRole("button", { name: "开始激活演示" }).click();
+  await expect(console).toHaveAttribute("data-phase", "agent");
+  await expect(console.locator("[data-log] li")).toHaveCount(2);
+  await console.getByRole("button", { name: /Claude Code/ }).click();
+  await console.getByRole("button", { name: /配置模型服务/ }).click();
+  await console.getByRole("button", { name: /PPIO/ }).click();
+  await console.getByRole("button", { name: "验证示例连接" }).click();
+  await expect(console).toHaveAttribute("data-phase", "model");
+  await console.getByRole("button", { name: "deepseek/deepseek-v3" }).click();
+  await console.getByRole("button", { name: "确认激活" }).click();
+  await expect(console).toHaveAttribute("data-phase", "ready");
+  await expect(console.locator("[data-log]")).toContainText("示例协议验证完成");
+  const animations = await console.evaluate((element) =>
+    element.getAnimations({ subtree: true }).filter((animation) => animation.playState === "running").length,
+  );
+  expect(animations).toBe(0);
+});
+
+/* The landing page has to show what activation looks like to someone who clicks
+   nothing at all — that is the whole reason autoplay exists. */
+test("activation demo plays itself through to Ready without a click", async ({ page }) => {
+  const fetches: string[] = [];
+  page.on("request", (request) => {
+    if (["fetch", "xhr"].includes(request.resourceType())) fetches.push(request.url());
+  });
+  await page.goto("/");
+  const console = page.locator("#activation-console");
+  await console.scrollIntoViewIfNeeded();
+
+  await expect(console).toHaveAttribute("data-phase", "ready");
+  await expect(console.getByRole("heading", { name: "示例环境已 Ready" })).toBeVisible();
+  // Reaching the end clears the flag, so the visitor is in charge from here.
+  await expect(console).not.toHaveAttribute("data-autoplaying", "true");
+  await expect(console.locator("[data-log]")).toContainText("示例环境可进入 Ready");
+  expect(fetches, "an unattended demo must not call anything either").toEqual([]);
+});
+
+// Autoplay is a demonstration, not a ride: the moment someone reaches for the
+// console it belongs to them, and it must not resume behind their back.
+test("interacting during autoplay stops it where it stands", async ({ page }) => {
+  await page.goto("/");
+  const console = page.locator("#activation-console");
+  await console.scrollIntoViewIfNeeded();
+  await expect(console).toHaveAttribute("data-autoplaying", "true");
+
+  /* Waits for a step that is a decision point. Taking over during `scanning`
+     would still land on `agent`, because the scan's own timer resolves it the
+     same way a clicked run does — leaving a spinner up forever would be the
+     worse behaviour. `agent` is the first step where the demo is genuinely
+     waiting on a choice, so it is where "stopped" is observable. */
+  await expect(console).toHaveAttribute("data-phase", "agent");
+  await console.locator("[data-log]").click();
+  await expect(console).not.toHaveAttribute("data-autoplaying", "true");
+  await page.waitForTimeout(2500);
+  expect(await console.getAttribute("data-phase"), "autoplay resumed after takeover").toBe("agent");
+
+  // Taken over, not broken: the trigger still replays from the top.
+  await page.getByRole("button", { name: "开始激活演示" }).click();
+  await expect(console).toHaveAttribute("data-phase", "agent");
+  await expect(console).not.toHaveAttribute("data-autoplaying", "true");
+});
+
+/* The failure this guards is specific and easy to reintroduce: every step calls
+   focusPanel, and if autoplay keeps doing that it steals focus from whatever the
+   visitor is reading or tabbing through — on a page they never interacted with. */
+test("autoplay never takes keyboard focus", async ({ page }) => {
+  await page.goto("/");
+  const console = page.locator("#activation-console");
+  await console.scrollIntoViewIfNeeded();
+
+  const insideConsole = () =>
+    page.evaluate(() => Boolean(document.querySelector("#activation-console")?.contains(document.activeElement)));
+  for (let sample = 0; sample < 12; sample += 1) {
+    expect(await insideConsole(), "autoplay moved focus into the console").toBe(false);
+    await page.waitForTimeout(250);
+  }
+  await expect(console).toHaveAttribute("data-phase", "ready");
+});
+
+test("Explorer restores shareable state and returns focus after the drawer closes", async ({ page }) => {
+  await page.goto("/explore/?agent=claude-code&provider=ppio&platform=macos&protocol=anthropic");
+  const explorer = page.locator("compatibility-explorer");
+  const drawer = explorer.locator("[data-explorer-drawer]");
+  await expect(drawer).toBeVisible();
+  await expect(drawer.getByRole("heading", { name: "Claude Code" })).toBeVisible();
+  await expect(explorer.locator('[data-filter="platform"]')).toHaveValue("macos");
+  await expect(explorer.locator('[data-filter="provider"]')).toHaveValue("ppio");
+  await expect(explorer.locator('[data-filter="protocol"]')).toHaveValue("anthropic");
+
+  await drawer.getByRole("button", { name: "关闭详情" }).click();
+  await expect(page).not.toHaveURL(/agent=/);
+
+  const card = explorer.locator('[data-agent-card][data-agent-id="claude-code"]');
+  await card.focus();
+  await page.keyboard.press("Enter");
+  await expect(drawer).toBeVisible();
+  await page.keyboard.press("Escape");
+  await expect(drawer).toBeHidden();
+  await expect(card).toBeFocused();
+});
+
+test("Explorer filters only catalog-backed combinations", async ({ page }) => {
+  await page.goto("/explore/");
+  const explorer = page.locator("compatibility-explorer");
+  await explorer.locator('[data-filter="platform"]').selectOption("windows");
+  await explorer.locator('[data-filter="protocol"]').selectOption("responses");
+  await explorer.locator('[data-filter="provider"]').selectOption("ppio");
+  const visible = explorer.locator("[data-agent-card]:visible");
+  await expect(visible).toHaveCount(1);
+  await expect(visible).toHaveAttribute("data-agent-id", "codex");
+  await expect(page).toHaveURL(/platform=windows/);
+  await expect(page).toHaveURL(/protocol=responses/);
+  await expect(page).toHaveURL(/provider=ppio/);
+});
+
+/* The download page renders from whatever the GitHub Releases feed returned at
+   build time. With no published release the whole platform picker is replaced by
+   a "not published yet" notice, which is the correct page — but it means the
+   picker tests have nothing to drive.
+ *
+ * They skip rather than being deleted or loosened. A release exists in the repo
+ * this site ships from, so these assertions are the ones that catch a regression
+ * there; silently dropping them would mean the download flow rots unnoticed the
+ * next time a build does have artifacts. The skip reason names the cause so a red
+ * run is not mistaken for a broken picker.
+ */
+async function skipWithoutPublishedRelease(page: Page) {
   await page.goto("/downloads/");
-  const select = page.getByLabel("选择平台与架构");
-  await expect(select).toBeVisible();
-  await select.selectOption("windows-x64");
+  const hasPicker = await page.locator("[data-platform-picker]").count();
+  test.skip(hasPicker === 0, "no release is published, so the page renders the unavailable notice");
+}
+
+/* The expected digest used to be read from the site's own release-index.json and
+   compared against the page. That artifact is gone — release data now comes from
+   GitHub Releases at build time — so there is no second copy to cross-check
+   against, and asserting the shape of what the page prints is what remains. A
+   64-hex digest and a real download link are still worth gating: an empty or
+   truncated checksum is exactly what a reader cannot verify with. */
+test("download center recommends an available artifact but keeps manual choices", async ({ page }) => {
+  await skipWithoutPublishedRelease(page);
+  const picker = page.getByRole("group", { name: "选择平台与架构" });
+  await expect(picker).toBeVisible();
+  const platform = (id: string) => picker.locator(`input[type="radio"][value="${id}"]`);
+  await platform("windows-x64").check();
   await expect(page.getByRole("heading", { name: "这个平台尚未公开发行" })).toBeVisible();
-  await select.selectOption("macos-arm64");
+  await platform("macos-arm64").check();
   await expect(page.getByRole("link", { name: "下载 macOS 预览版" })).toBeVisible();
-  await expect(page.getByText(expectedSha, { exact: true })).toBeVisible();
+  await expect(page.locator("[data-release-panel].is-active .hash-value")).toHaveText(/^[a-f0-9]{64}$/);
   await expect(page.getByText("未签名、未公证", { exact: true })).toBeVisible();
 });
 
+/* Security and enterprise came out of the chrome, but the pages did not go
+   anywhere. The security page is where the release evidence, the privacy
+   statement and the Stable gate are written down, and the footer is now the only
+   route to it, so removing the nav entry and keeping the page reachable are
+   asserted together — otherwise a later cleanup drops the page and the trust
+   claims leave with it. The #privacy and #release-evidence anchors are checked
+   because other documents cite them directly, not just the page. */
+test("security and enterprise leave the navigation but stay reachable", async ({ page }) => {
+  for (const path of ["/", "/en/"]) {
+    await page.goto(path);
+    await expect(page.locator(".site-header").getByRole("link", { name: /安全|Security/ })).toHaveCount(0);
+    await expect(page.locator(".site-header").getByRole("link", { name: /企业服务|Enterprise/ })).toHaveCount(0);
+    await expect(page.locator(".site-footer").getByRole("link", { name: /安全与隐私|Security & privacy/ })).toHaveCount(0);
+    await expect(page.locator(".site-footer").getByRole("link", { name: /企业服务|Enterprise/ })).toHaveCount(0);
+    // The footer's other two entries are the only route to them, so they stay.
+    await expect(page.locator(".site-footer").getByRole("link", { name: /支持与反馈|Support & feedback/ })).toBeVisible();
+    await expect(page.locator(".site-footer").getByRole("link", { name: "GitHub Releases" })).toBeVisible();
+  }
+
+  for (const path of ["/security/", "/en/security/", "/enterprise/"]) {
+    const response = await page.goto(path);
+    expect(response?.status(), `${path} must stay published`).toBe(200);
+    await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
+  }
+  await page.goto("/security/");
+  await expect(page.locator("#privacy")).toBeAttached();
+  await expect(page.locator("#release-evidence")).toBeAttached();
+});
+
+// The picker is a real radio group rather than a styled listbox, so arrow keys
+// have to move the selection — that behaviour is the reason for the markup.
+test("platform picker is keyboard operable", async ({ page }) => {
+  await skipWithoutPublishedRelease(page);
+  const picker = page.getByRole("group", { name: "选择平台与架构" });
+  await picker.locator('input[value="macos-arm64"]').focus();
+  await page.keyboard.press("ArrowDown");
+  await expect(picker.locator('input[value="macos-x64"]')).toBeChecked();
+  await expect(page.locator('[data-release-panel="macos-x64"]')).toHaveClass(/is-active/);
+  await page.keyboard.press("ArrowUp");
+  await expect(picker.locator('input[value="macos-arm64"]')).toBeChecked();
+  await expect(page.getByRole("link", { name: "下载 macOS 预览版" })).toBeVisible();
+  // The ring belongs to the card, not the 16px dot inside it.
+  await expect(picker.locator('input[value="macos-arm64"]')).toHaveCSS("outline-style", "none");
+});
+
+// The detection note is a server-rendered localised template that the client
+// fills in from the DOM. Reading those templates off the wrong element leaves
+// every branch as an empty string, which blanks the note instead of failing
+// loudly — so both locales assert real text with no placeholder left behind.
+for (const [route, expected] of [
+  ["/downloads/", "已识别为"],
+  ["/en/downloads/", "Detected as"],
+] as const) {
+  test(`the download page explains its platform detection in the page's language (${route})`, async ({ page }) => {
+    await page.goto(route);
+    const note = page.locator("[data-detected-note]");
+    // The note lives inside the platform picker, which is absent when no release
+    // is published. Same reason as skipWithoutPublishedRelease above.
+    test.skip((await note.count()) === 0, "no release is published, so the page renders the unavailable notice");
+    await expect(note).toContainText(expected);
+    await expect(note).not.toContainText("{");
+  });
+}
+
 test("guide-only compatibility remains distinct from managed installation", async ({ page }) => {
   await page.goto("/agents/cursor/");
   await expect(page.getByText("按官方方式安装", { exact: true })).toBeVisible();
@@ -45,17 +396,21 @@ test("guide-only compatibility remains distinct from managed installation", asyn
   await expect(page.getByText("OneAgent 可管理安装", { exact: true })).toHaveCount(0);
 });
 
-test("public release index exposes the same verified artifact", async ({ request }) => {
-  const response = await request.get("/release-index.json");
-  expect(response.ok()).toBeTruthy();
-  const index = await response.json();
-  const preview = index.channels.find((channel: { channel: string }) => channel.channel === "technical-preview-unsigned");
-  const mac = preview.targets.find((target: { id: string }) => target.id === "macos-arm64");
-  expect(preview.version).toBe("0.2.0-dev");
-  expect(preview.unsigned).toBe(true);
-  expect(mac.verification.cleanroom).toBe("verified");
-  expect(mac.artifacts[0].sha256).toMatch(/^[a-f0-9]{64}$/);
-  expect(mac.artifacts[0].downloads.some((download: { kind: string; primary: boolean }) => download.kind === "official" && download.primary)).toBe(true);
+/* Replaces a test that fetched the site's own release-index.json and asserted the
+   artifact it published. The site no longer publishes that file, so the guarantee
+   worth keeping is the one a reader depends on: the download page states the
+   channel honestly, prints a digest they can check, and sends them to the
+   official release rather than a mirror the site invented. */
+test("download page states the channel and links to the official release", async ({ page }) => {
+  await skipWithoutPublishedRelease(page);
+  /* Scoped to the active panel throughout. All four platform panels are in the
+     DOM and only CSS hides the inactive ones, so an unscoped text match resolves
+     against a hidden copy first and fails on visibility. */
+  const active = page.locator("[data-release-panel].is-active");
+  await expect(active.getByText("未签名技术预览版", { exact: true })).toBeVisible();
+  await expect(active.locator(".hash-value")).toHaveText(/^[a-f0-9]{64}$/);
+  const download = active.getByRole("link", { name: /下载 .* 预览版/ });
+  await expect(download).toHaveAttribute("href", /^https:\/\/github\.com\/[^/]+\/[^/]+\/releases\/download\//);
 });
 
 test("serves its own stylesheet and Agent marks rather than 404ing on them", async ({ page }) => {
@@ -71,13 +426,38 @@ test("serves its own stylesheet and Agent marks rather than 404ing on them", asy
   await page.goto("/agents/", { waitUntil: "networkidle" });
   expect(missing, "every asset the page asks for must exist").toEqual([]);
   // A stylesheet that failed to load leaves the UA default, not this palette.
-  await expect(page.locator("body")).toHaveCSS("background-color", "rgb(244, 243, 239)");
+  await expect(page.locator("body")).toHaveCSS("background-color", "rgb(236, 236, 239)");
   const brokenMarks = await page.evaluate(
     () => document.images.length && [...document.images].filter((image) => !image.complete || image.naturalWidth === 0).length,
   );
   expect(brokenMarks, "Agent marks must render").toBe(0);
 });
 
+test.describe("hero particles", () => {
+  const frameDigest = (path: string) =>
+    `(() => { const c = document.querySelector('${path}'); const d = c.getContext('2d').getImageData(0, 0, c.width, c.height).data; let h = 0; for (let i = 0; i < d.length; i += 97) h = (h * 31 + d[i]) | 0; return h; })()`;
+
+  test("animates by default", async ({ page }) => {
+    await page.goto("/");
+    const canvas = page.locator("[data-hero-particles]");
+    await expect(canvas).toHaveAttribute("aria-hidden", "true");
+    const first = await page.evaluate(frameDigest("[data-hero-particles]"));
+    await page.waitForTimeout(400);
+    expect(await page.evaluate(frameDigest("[data-hero-particles]"))).not.toBe(first);
+  });
+
+  // The CSS prefers-reduced-motion block only clamps CSS animations, so the
+  // canvas has to opt out in script. Only a real reduced-motion context proves it.
+  test("paints a static frame under reduced motion", async ({ browser }) => {
+    const page = await browser.newPage({ reducedMotion: "reduce" });
+    await page.goto("/");
+    const first = await page.evaluate(frameDigest("[data-hero-particles]"));
+    await page.waitForTimeout(400);
+    expect(await page.evaluate(frameDigest("[data-hero-particles]"))).toBe(first);
+    await page.close();
+  });
+});
+
 test("ships a local-only content policy and no third-party scripts", async ({ page }) => {
   await page.goto("/");
   const policy = await page.locator('meta[http-equiv="Content-Security-Policy"]').getAttribute("content");
@@ -100,3 +480,330 @@ for (const path of criticalPages) {
     expect(serious, JSON.stringify(serious, null, 2)).toEqual([]);
   });
 }
+
+// axe treats <canvas> as an image node and gives up resolving the background
+// behind it, so every hero and header text node comes back "incomplete" rather
+// than pass — the particle layer hides exactly the copy most worth checking.
+// Dropping the decoration first is what actually gates those colours.
+test("hero text contrast is proven once the decorative canvas is removed", async ({ page }) => {
+  await page.goto("/");
+  await page.addScriptTag({ content: axe.source });
+  const result = await page.evaluate(async () => {
+    document.querySelector("[data-hero-particles]")?.remove();
+    const axeApi = (window as typeof window & { axe: typeof axe }).axe;
+    return axeApi.run(document, { runOnly: ["color-contrast"] });
+  });
+  expect(result.violations, JSON.stringify(result.violations, null, 2)).toEqual([]);
+  expect(result.incomplete, JSON.stringify(result.incomplete, null, 2)).toEqual([]);
+});
+
+// Navigation animates via the native cross-document path, so the proof is that
+// the outgoing document reports a live transition on pageswap. Asserting on the
+// CSS alone would still pass if the browser declined to run it.
+// Below 920px the nav collapses into a disclosure menu, and the transition is a
+// document-level behaviour that does not vary by viewport — one width proves it.
+test("navigating between pages runs a cross-document view transition", async ({ page, viewport }) => {
+  test.skip((viewport?.width ?? 0) < 920, "nav links are collapsed at this width");
+  await page.goto("/");
+  await page.evaluate(() => {
+    window.addEventListener("pageswap", (event) => {
+      sessionStorage.setItem("vt-ran", (event as PageSwapEvent).viewTransition ? "yes" : "no");
+    });
+  });
+  await page.getByLabel("主导航").getByRole("link", { name: "配置", exact: true }).click();
+  await expect(page).toHaveURL(/\/explore\/$/);
+  expect(await page.evaluate(() => sessionStorage.getItem("vt-ran"))).toBe("yes");
+  // The shared chrome opts out of the crossfade by being named on both pages.
+  await expect(page.locator(".site-header")).toHaveCSS("view-transition-name", "site-header");
+});
+
+test.describe("hero entrance", () => {
+  const heroParts = [".eyebrow", ".display", ".lede", ".hero-actions", ".hero-note", ".product-shot"];
+
+  test("staggers the hero into place on first paint", async ({ page, viewport }) => {
+    await page.goto("/");
+    const delays = await page.evaluate(() =>
+      document
+        .getAnimations()
+        .filter((animation) => (animation as CSSAnimation).animationName === "hero-rise")
+        .map((animation) => Number((animation.effect as KeyframeEffect).getTiming().delay))
+        .sort((a, b) => a - b),
+    );
+    if ((viewport?.width ?? 0) <= 680) {
+      // Stacked layout moves the block, not the lines — see the note in global.css.
+      expect(delays).toEqual([0, 180]);
+    } else {
+      expect(delays).toEqual([0, 70, 160, 230, 290, 360]);
+    }
+  });
+
+  // The previous attempt faded these in, which dropped the largest type on the
+  // site below AA for the whole animation. Auditing only the settled page would
+  // not have caught it, so sample while the entrance is still running.
+  test("keeps hero text readable while the entrance runs", async ({ page }) => {
+    await page.goto("/");
+    await page.addScriptTag({ content: axe.source });
+    const worst = await page.evaluate(async (parts) => {
+      document.querySelector("[data-hero-particles]")?.remove();
+      for (const selector of [...parts, ".hero-copy"]) {
+        const element = document.querySelector<HTMLElement>(selector);
+        if (!element) continue;
+        element.style.animation = "none";
+        void element.offsetHeight;
+        element.style.animation = "";
+      }
+      const axeApi = (window as typeof window & { axe: typeof axe }).axe;
+      let violations = 0;
+      for (let sample = 0; sample < 4; sample += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 90));
+        const result = await axeApi.run(document, { runOnly: ["color-contrast"] });
+        violations += result.violations.reduce((total, entry) => total + entry.nodes.length, 0);
+      }
+      return violations;
+    }, heroParts);
+    expect(worst, "hero copy must clear AA at every frame of the entrance").toBe(0);
+  });
+});
+
+test.describe("english locale", () => {
+  // Derived from the route list rather than written out, so adding a translation
+  // without auditing its English page is not possible.
+  const englishPages = translatedRoutes.map((route) => `/en/${route}`);
+
+  for (const path of englishPages) {
+    test(`has no serious accessibility violations: ${path}`, async ({ page }) => {
+      await page.goto(path);
+      await expect(page.locator("html")).toHaveAttribute("lang", "en");
+      await page.addScriptTag({ content: axe.source });
+      const result = await page.evaluate(async () => {
+        document.querySelector("[data-hero-particles]")?.remove();
+        const axeApi = (window as typeof window & { axe: typeof axe }).axe;
+        return axeApi.run(document, { runOnly: { type: "tag", values: ["wcag2a", "wcag2aa"] } });
+      });
+      const serious = result.violations.filter(
+        (violation) => violation.impact === "serious" || violation.impact === "critical",
+      );
+      expect(serious, JSON.stringify(serious, null, 2)).toEqual([]);
+    });
+  }
+
+  test("declares reciprocal hreflang alternates with an x-default", async ({ page }) => {
+    for (const path of ["/", "/en/", "/explore/", "/en/explore/", "/security/", "/en/security/"]) {
+      await page.goto(path);
+      const codes = await page.evaluate(() =>
+        [...document.querySelectorAll('link[rel="alternate"][hreflang]')].map((link) => link.getAttribute("hreflang")),
+      );
+      expect(new Set(codes), `alternates on ${path}`).toEqual(new Set(["zh-CN", "en", "x-default"]));
+    }
+  });
+
+  // An untranslated route falls back to Chinese rather than 404ing, which is the
+  // right call — but silently swapping the reader's language mid-navigation is
+  // not. Every link that does it has to say so before the click.
+  test("marks links that fall back to Chinese, and only on English pages", async ({ page }) => {
+    await page.goto("/en/");
+    /* Security and enterprise left the nav, so the specific links this used to
+       name are gone. The sweep below is the real guarantee and covers whatever
+       is in the nav now — including the CTA band's untranslated team-services
+       link, which is where the hint has to appear on this page. */
+
+    // Every link leaving /en/ for an untranslated route carries the hint.
+    const unmarked = await page.evaluate((translated) => {
+      return [...document.querySelectorAll("a[href^='/']")]
+        .filter((link) => {
+          const href = link.getAttribute("href") ?? "";
+          if (href.startsWith("/en/") || /\.(json|txt|webmanifest)$/.test(href)) return false;
+          const route = href.replace(/^\//, "");
+          return !translated.includes(route);
+        })
+        .filter((link) => !link.querySelector(".lang-hint"))
+        .map((link) => link.getAttribute("href"));
+    }, translatedRoutes);
+    expect(unmarked, "these links change language without saying so").toEqual([]);
+
+    // The hint is about leaving English; a Chinese reader is already there.
+    await page.goto("/");
+    await expect(page.locator(".lang-hint")).toHaveCount(0);
+  });
+
+  // Switching language has to keep the reader on the page they were reading;
+  // dropping them on the home page is the usual failure here.
+  test("language switch stays on the equivalent page", async ({ page, viewport }) => {
+    test.skip((viewport?.width ?? 0) < 920, "header actions are collapsed at this width");
+    await page.goto("/downloads/");
+    await page.getByRole("link", { name: "切换语言" }).click();
+    await expect(page).toHaveURL(/\/en\/downloads\/$/);
+    await expect(page.locator("html")).toHaveAttribute("lang", "en");
+
+    await page.getByRole("link", { name: "Change language" }).click();
+    await expect(page).toHaveURL(/\/downloads\/$/);
+    await expect(page.locator("html")).toHaveAttribute("lang", "zh-CN");
+  });
+
+  test("language switch preserves the Explorer route", async ({ page, viewport }) => {
+    test.skip((viewport?.width ?? 0) < 920, "header actions are collapsed at this width");
+    await page.goto("/explore/?platform=macos");
+    await page.getByRole("link", { name: "切换语言" }).click();
+    await expect(page).toHaveURL(/\/en\/explore\/$/);
+    await expect(page.locator("html")).toHaveAttribute("lang", "en");
+    await page.getByRole("link", { name: "Change language" }).click();
+    await expect(page).toHaveURL(/\/explore\/$/);
+  });
+
+  // Every link on an English page must resolve; an untranslated destination is
+  // expected to fall back to Chinese rather than 404 under /en/.
+  test("navigation from an english page never lands on a missing route", async ({ page }) => {
+    const missing: string[] = [];
+    page.on("response", (response) => {
+      if (response.status() >= 400) missing.push(`${response.status()} ${new URL(response.url()).pathname}`);
+    });
+    await page.goto("/en/", { waitUntil: "networkidle" });
+    const targets = await page.evaluate(() =>
+      [...document.querySelectorAll<HTMLAnchorElement>("a[href]")]
+        .map((anchor) => anchor.href)
+        .filter((href) => href.startsWith(location.origin)),
+    );
+    for (const target of new Set(targets)) {
+      const response = await page.request.get(target);
+      expect(response.status(), `${target} from /en/`).toBeLessThan(400);
+    }
+    expect(missing, "assets on /en/ must all exist").toEqual([]);
+  });
+});
+
+test.describe("dark scheme", () => {
+  // The light palette needed five values darkened to clear AA; the dark one is a
+  // second, independent set of colours over different grounds, so it needs the
+  // same gate rather than an assumption that inverting is safe.
+  for (const path of criticalPages) {
+    test(`has no serious accessibility violations in the dark: ${path}`, async ({ page }) => {
+      await page.emulateMedia({ colorScheme: "dark" });
+      await page.goto(path);
+      await expect(page.locator("html")).toHaveClass(/theme-dark/);
+      await page.addScriptTag({ content: axe.source });
+      const result = await page.evaluate(async () => {
+        document.querySelector("[data-hero-particles]")?.remove();
+        const axeApi = (window as typeof window & { axe: typeof axe }).axe;
+        return axeApi.run(document, { runOnly: { type: "tag", values: ["wcag2a", "wcag2aa"] } });
+      });
+      const serious = result.violations.filter(
+        (violation) => violation.impact === "serious" || violation.impact === "critical",
+      );
+      expect(serious, JSON.stringify(serious, null, 2)).toEqual([]);
+    });
+  }
+
+  // axe does not measure image contrast, so nothing above would have caught the
+  // Codex and OpenCode marks going invisible: they are fill="currentColor" and an
+  // <img> resolves that to black regardless of the page.
+  test("keeps currentColor agent marks visible without touching brand marks", async ({ page }) => {
+    await page.emulateMedia({ colorScheme: "dark" });
+    await page.goto("/agents/");
+    const filters = await page.evaluate(() =>
+      [...document.querySelectorAll<HTMLImageElement>(".agent-mark-wrap img")].map((image) => ({
+        file: image.src.split("/").pop() ?? "",
+        monochrome: image.hasAttribute("data-monochrome"),
+        filter: getComputedStyle(image).filter,
+      })),
+    );
+    const monochrome = filters.filter((entry) => entry.monochrome);
+    expect(monochrome.map((entry) => entry.file).sort()).toEqual(["codex.svg", "opencode.svg"]);
+    for (const entry of monochrome) expect(entry.filter, entry.file).toBe("invert(1)");
+    for (const entry of filters.filter((entry) => !entry.monochrome)) {
+      expect(entry.filter, `${entry.file} carries its own colours`).toBe("none");
+    }
+
+    await page.emulateMedia({ colorScheme: "light" });
+    await page.goto("/agents/");
+    const light = await page.evaluate(() =>
+      [...document.querySelectorAll<HTMLImageElement>(".agent-mark-wrap img")].map(
+        (image) => getComputedStyle(image).filter,
+      ),
+    );
+    expect(new Set(light), "no mark is inverted in the light scheme").toEqual(new Set(["none"]));
+  });
+
+  test("remembers an explicit choice over the system preference", async ({ page }) => {
+    await page.emulateMedia({ colorScheme: "light" });
+    await page.goto("/");
+    await expect(page.locator("html")).not.toHaveClass(/theme-dark/);
+
+    const toggle = page.getByRole("button", { name: "切换深色模式" });
+    await toggle.click();
+    await expect(page.locator("html")).toHaveClass(/theme-dark/);
+    await expect(toggle).toHaveAttribute("aria-pressed", "true");
+
+    // The inline head script is what makes the choice survive without a flash.
+    await page.reload();
+    await expect(page.locator("html")).toHaveClass(/theme-dark/);
+    await expect(page.getByRole("button", { name: "切换深色模式" })).toHaveAttribute("aria-pressed", "true");
+
+    await page.getByRole("button", { name: "切换深色模式" }).click();
+    await expect(page.locator("html")).not.toHaveClass(/theme-dark/);
+    await page.reload();
+    await expect(page.locator("html")).not.toHaveClass(/theme-dark/);
+  });
+
+  test("paints the resolved theme before first contentful paint", async ({ page }) => {
+    await page.emulateMedia({ colorScheme: "dark" });
+    await page.goto("/", { waitUntil: "commit" });
+    // Sampling at commit catches a theme applied late: if the class were set by
+    // the deferred module script, the light palette would paint first.
+    expect(await page.evaluate(() => document.documentElement.className)).toContain("theme-dark");
+  });
+});
+
+// The interactive console must share the hero copy measure and size to its own
+// content at every breakpoint. A clipped wizard can visually cover the next
+// section even when overflow hides the pixels.
+test("the activation console sits on the same measure as the copy", async ({ page }) => {
+  await page.goto("/");
+  await page.evaluate(() =>
+    Promise.all(
+      document
+        .getAnimations()
+        .filter((animation) => (animation as CSSAnimation).animationName === "hero-rise")
+        .map((animation) => animation.finished),
+    ),
+  );
+  const layout = await page.evaluate(() => {
+    const edges = (selector: string) => {
+      const rect = document.querySelector(selector)!.getBoundingClientRect();
+      return { left: Math.round(rect.left), right: Math.round(rect.right) };
+    };
+    const panel = document.querySelector<HTMLElement>("[data-console-window]")!;
+    const rect = panel.getBoundingClientRect();
+    return {
+      copy: edges(".hero-copy"),
+      console: edges(".product-shot"),
+      contentOverflow: panel.scrollHeight - Math.round(rect.height),
+      gapBelowConsole: Math.round(
+        document.querySelector(".hero + .section")!.getBoundingClientRect().top -
+          document.querySelector(".product-shot")!.getBoundingClientRect().bottom,
+      ),
+    };
+  });
+  expect(layout.console).toEqual(layout.copy);
+  expect(layout.contentOverflow, "the activation console must not clip its own content").toBeLessThanOrEqual(1);
+  expect(layout.gapBelowConsole, "the console must not butt against the next section").toBeGreaterThan(16);
+});
+
+// Synthetic mouse events never set :hover, so the resting-vs-hovered difference
+// is only observable by moving a real pointer.
+test("interactive rows and cards respond to hover", async ({ page, viewport }) => {
+  test.skip((viewport?.width ?? 0) < 920, "hover is not the primary input at this width");
+
+  await page.goto("/agents/");
+  const row = page.locator(".agent-row").first();
+  await expect(row).toHaveCSS("background-color", "rgba(0, 0, 0, 0)");
+  await row.hover();
+  await expect(row).toHaveCSS("background-color", "rgb(255, 255, 255)");
+  await expect(row).not.toHaveCSS("box-shadow", "none");
+
+  await page.goto("/providers/");
+  const card = page.locator(".provider-card").first();
+  const restingBorder = await card.evaluate((el) => getComputedStyle(el).borderColor);
+  await card.hover();
+  await expect(card).not.toHaveCSS("border-color", restingBorder);
+  await expect(card).not.toHaveCSS("transform", "none");
+});
diff --git a/site/package-lock.json b/site/package-lock.json
index 97199963..d22570a0 100644
--- a/site/package-lock.json
+++ b/site/package-lock.json
@@ -6,7 +6,6 @@
   "packages": {
     "": {
       "name": "oneagent-public-site",
-      "version": "0.2.0-dev",
       "dependencies": {
         "@astrojs/sitemap": "3.7.3",
         "astro": "7.1.4"
diff --git a/site/package.json b/site/package.json
index 54efab28..bc1fa89b 100644
--- a/site/package.json
+++ b/site/package.json
@@ -1,12 +1,10 @@
 {
   "name": "oneagent-public-site",
-  "version": "0.2.0-dev",
   "private": true,
   "type": "module",
   "scripts": {
-    "prepare:data": "python3.12 ../scripts/build_release_index.py --release-dir ../release --channels ../distribution/channels.json --output src/generated/release-index.json --copy-downloads public/downloads && python3.12 ../scripts/build_site_catalog.py --lock ../agents.lock.json --providers ../distribution/providers.json --output src/generated/catalog.json",
-    "dev": "npm run prepare:data && astro dev",
-    "build": "npm run prepare:data && npm run check && astro build && npm run validate",
+    "dev": "astro dev",
+    "build": "npm run check && astro build && npm run validate",
     "check": "astro check",
     "test": "vitest run",
     "test:e2e": "playwright test",
diff --git a/site/playwright.config.ts b/site/playwright.config.ts
index d97c616a..8c9a6aa2 100644
--- a/site/playwright.config.ts
+++ b/site/playwright.config.ts
@@ -4,6 +4,14 @@ export default defineConfig({
   testDir: "./e2e",
   fullyParallel: true,
   reporter: "list",
+  /* Trace teardown writes its zip inside the per-test budget, and on a full
+     three-project parallel run that write was itself timing out — turning
+     passing tests into failures whose only error was "Fixture 'trace recording'
+     timeout during teardown". The suite is ~1.4 min without it and was 4-7 min
+     with it. Traces are still captured on failure; they just get their own room
+     to finish, and the per-test budget is no longer shared with the recorder. */
+  timeout: 60_000,
+  expect: { timeout: 10_000 },
   use: {
     baseURL: "http://127.0.0.1:4321",
     trace: "retain-on-failure",
diff --git a/site/public/llms.txt b/site/public/llms.txt
new file mode 100644
index 00000000..a2d9e781
--- /dev/null
+++ b/site/public/llms.txt
@@ -0,0 +1,38 @@
+# OneAgent
+
+> A trustworthy local AI development environment activator. It detects, installs
+> and configures CLI coding agents to point at an OpenAI- or Anthropic-compatible
+> provider of your choosing. Everything runs locally.
+
+Current release: 0.2.0-dev, published only as `technical-preview-unsigned`.
+The build is unsigned and unnotarised, and is never described as stable.
+
+## Product boundary
+
+- Runs locally. Configuration and backups stay on the user's device.
+- Bring your own key. There is no shared key and no unified model gateway.
+- Model requests are never proxied through OneAgent.
+- Third-party agent binaries are not redistributed; agents come from their
+  official sources.
+- Every distribution channel serves a byte-identical build with the same
+  SHA-256.
+
+## Pages
+
+- /: overview, first-success path, agent compatibility
+- /downloads/: per-platform artifacts with size, build date and SHA-256
+- /quickstart/: download through to a verified first agent configuration
+- /agents/: which agents OneAgent can install and configure, stated separately
+- /providers/: provider protocol support and commercial-relationship disclosure
+- /security/: local execution, key handling, backups, release integrity
+- /changelog/: shipped changes only
+- /enterprise/: team enablement and environment baselines
+- /release-index.json: machine-readable release index
+
+English translations exist for /en/, /en/downloads/ and /en/quickstart/.
+
+## Notes for machine readers
+
+Support is stated as three separate facts — managed install, managed
+configuration, and protocol — because a single "supported" checkmark would
+misrepresent guide-only agents. Do not collapse them.
diff --git a/site/public/site.webmanifest b/site/public/site.webmanifest
new file mode 100644
index 00000000..70f2b9be
--- /dev/null
+++ b/site/public/site.webmanifest
@@ -0,0 +1,10 @@
+{
+  "name": "OneAgent",
+  "short_name": "OneAgent",
+  "description": "A trustworthy local AI development environment activator.",
+  "start_url": "./",
+  "display": "browser",
+  "background_color": "#ececef",
+  "theme_color": "#ececef",
+  "icons": [{ "src": "favicon.svg", "type": "image/svg+xml", "sizes": "any" }]
+}
diff --git a/site/scripts/validate-build.mjs b/site/scripts/validate-build.mjs
index cf9488ec..bb76224f 100644
--- a/site/scripts/validate-build.mjs
+++ b/site/scripts/validate-build.mjs
@@ -34,7 +34,14 @@ function localTarget(href) {
 }
 
 walk(rootPath);
-for (const required of ["index.html", "downloads/index.html", "quickstart/index.html", "agents/index.html", "providers/index.html", "security/index.html", "release-index.json"]) {
+// The /en/ entries are listed for the same reason as the rest: a translated page
+// silently dropping out of the build is otherwise invisible, since the link
+// checker below only sees links that were actually emitted.
+//
+// release-index.json is no longer among them: the site reads release data from
+// GitHub Releases at build time instead of republishing a locally generated
+// index, so there is no such artifact to require.
+for (const required of ["index.html", "downloads/index.html", "quickstart/index.html", "agents/index.html", "providers/index.html", "security/index.html", "explore/index.html", "en/index.html", "en/downloads/index.html", "en/quickstart/index.html", "en/explore/index.html", "en/security/index.html", "llms.txt", "site.webmanifest"]) {
   if (!existsSync(join(rootPath, required))) failures.push(`Missing required output: ${required}`);
 }
 
@@ -52,6 +59,20 @@ for (const path of htmlFiles) {
   else if (!new URL(socialImage).pathname.startsWith(`${configuredBasePrefix}images/`)) failures.push(`${label} has an Open Graph image outside the base path: ${socialImage}`);
   if (/<script[^>]+src=["']https?:\/\//i.test(text) || /<img[^>]+src=["']https?:\/\//i.test(text) || /<link[^>]+rel=["']stylesheet["'][^>]+href=["']https?:\/\//i.test(text)) failures.push(`${label} loads a remote script, image, or stylesheet`);
   if (/sk-[A-Za-z0-9_-]{20,}/.test(text)) failures.push(`${label} appears to contain an API key`);
+  // A page's declared language has to match the directory it was emitted into,
+  // and any hreflang set has to be reciprocal and carry an x-default. Neither is
+  // visible to the link check below, which only sees hrefs.
+  const declaredLang = text.match(/<html lang="([^"]+)"/)?.[1];
+  const expectedLang = label.startsWith("en/") || label === "en.html" ? "en" : "zh-CN";
+  if (!declaredLang) failures.push(`${label} is missing a lang attribute`);
+  else if (declaredLang !== expectedLang) failures.push(`${label} declares lang="${declaredLang}" but sits under ${expectedLang}`);
+  const alternates = [...text.matchAll(/<link rel="alternate" hreflang="([^"]+)"/g)].map(([, code]) => code);
+  if (alternates.length && !alternates.includes("x-default")) {
+    failures.push(`${label} declares hreflang alternates without an x-default`);
+  }
+  if (alternates.length && !(alternates.includes("en") && alternates.includes("zh-CN"))) {
+    failures.push(`${label} declares an incomplete hreflang set: ${alternates.join(", ")}`);
+  }
   const matches = text.matchAll(/(?:href|src)="([^"]+)"/g);
   for (const [, href] of matches) {
     if (configuredBase && href.startsWith("/") && !href.startsWith(configuredBasePrefix) && !href.startsWith("//")) {
@@ -62,24 +83,21 @@ for (const path of htmlFiles) {
   }
 }
 
-const index = JSON.parse(readFileSync(join(rootPath, "release-index.json"), "utf8"));
-for (const channel of index.channels) {
-  for (const target of channel.targets) {
-    if (target.status !== "available") continue;
-    for (const artifact of target.artifacts) {
-      const path = join(rootPath, "downloads", artifact.file);
-      if (!existsSync(path)) {
-        failures.push(`Available artifact is missing from site output: ${artifact.file}`);
-        continue;
-      }
-      const digest = createHash("sha256").update(readFileSync(path)).digest("hex");
-      if (digest !== artifact.sha256) failures.push(`Published artifact hash drift: ${artifact.file}`);
-    }
-  }
-}
-
+/* This used to re-hash every artifact in dist/downloads/ and compare it against
+ * the digest the release index claimed, catching a page that printed a checksum
+ * the file did not actually have.
+ *
+ * That check has no subject any more. The site no longer hosts the artifacts —
+ * it links to GitHub Releases and prints the digest the API reported, so there
+ * is no local file to hash and nothing to compare a second opinion against. Be
+ * aware of what that costs: a wrong digest from the release feed now reaches the
+ * page unchallenged, where previously it could not survive the build.
+ *
+ * Restoring an equivalent gate means fetching each asset during validation and
+ * hashing it, which is a network round trip per artifact.
+ */
 if (failures.length) {
   console.error(failures.join("\n"));
   process.exit(1);
 }
-console.log(`Validated ${htmlFiles.length} HTML pages and all published release artifacts.`);
+console.log(`Validated ${htmlFiles.length} HTML pages.`);
diff --git a/site/scripts/verify-dev-base.mjs b/site/scripts/verify-dev-base.mjs
new file mode 100644
index 00000000..2ac4d0c8
--- /dev/null
+++ b/site/scripts/verify-dev-base.mjs
@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const host = "127.0.0.1";
+const port = 4322;
+const origin = `http://${host}:${port}`;
+const canonicalOrigin = "https://oneagent.example";
+const astroBin = fileURLToPath(new URL("../node_modules/astro/bin/astro.mjs", import.meta.url));
+const child = spawn(process.execPath, [astroBin, "dev", "--host", host, "--port", String(port)], {
+  cwd: new URL("..", import.meta.url),
+  env: { ...process.env, SITE_URL: canonicalOrigin, BASE_PATH: "/" },
+  stdio: ["ignore", "pipe", "pipe"],
+});
+
+let output = "";
+child.stdout.on("data", (chunk) => { output += chunk; });
+child.stderr.on("data", (chunk) => { output += chunk; });
+
+async function waitForPage() {
+  let lastError;
+  for (let attempt = 0; attempt < 80; attempt += 1) {
+    try {
+      const response = await fetch(origin);
+      if (response.ok) return response.text();
+      lastError = new Error(`HTTP ${response.status}`);
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw lastError ?? new Error("Astro dev server did not start");
+}
+
+try {
+  const html = await waitForPage();
+  const base = html.match(/<base href="([^"]+)"/i)?.[1];
+  const canonical = html.match(/<link rel="canonical" href="([^"]+)"/i)?.[1];
+  assert.equal(base, `${origin}/`, "runtime <base> must follow the active dev origin");
+  assert.equal(canonical, `${canonicalOrigin}/`, "canonical must continue to use SITE_URL");
+  console.log(`Verified dev base ${base} with canonical ${canonical}`);
+} catch (error) {
+  console.error(output);
+  throw error;
+} finally {
+  child.kill("SIGTERM");
+  await new Promise((resolve) => {
+    const stop = spawn(process.execPath, [astroBin, "dev", "stop"], {
+      cwd: new URL("..", import.meta.url),
+      env: { ...process.env, SITE_URL: canonicalOrigin, BASE_PATH: "/" },
+      stdio: "ignore",
+    });
+    stop.once("exit", resolve);
+    stop.once("error", resolve);
+  });
+}
diff --git a/site/src/components/ActivationConsole.astro b/site/src/components/ActivationConsole.astro
new file mode 100644
index 00000000..c9c8ad77
--- /dev/null
+++ b/site/src/components/ActivationConsole.astro
@@ -0,0 +1,1485 @@
+---
+import AgentMark from "./AgentMark.astro";
+import { catalog } from "../lib/catalog";
+import { bestLocaleFor, localeFromPath, localePath, switchesLanguage } from "../i18n";
+import { DEMO_CUSTOM_MODEL_HINT, demoStateFor } from "../lib/demo-environment";
+import { recommendedCombination } from "../lib/explorer";
+
+interface Props {
+  id?: string;
+}
+
+const { id = "activation-console" } = Astro.props;
+const locale = localeFromPath(Astro.url.pathname);
+const featuredAgents = catalog.agents.slice(0, 4);
+const recommendation = recommendedCombination(catalog);
+const href = (path: string) => localePath(bestLocaleFor(locale, path), path);
+const copy = locale === "en"
+  ? {
+      label: "Interactive product evidence",
+      sample: "Demo environment",
+      title: "Activation console",
+      subtitle: "A guided example. This page never scans your device or asks for an API key.",
+      idleTitle: "Ready when you are.",
+      idleBody: "Start from the hero action. OneAgent will walk through an example environment without touching this computer.",
+      scanningTitle: "Scanning the example environment",
+      scanningBody: "Reading a deterministic demo scenario — not your browser, files or local services.",
+      agentTitle: "Choose an agent",
+      agentBody: "Capabilities and locked versions come from the repository catalog. Machine state is explicitly illustrative.",
+      providerTitle: "Choose a provider",
+      providerBody: "Compatibility is calculated from the protocol registry. A preview gate never becomes Ready.",
+      verify: "Verify sample connection",
+      verifyingTitle: "Verifying the sample protocol",
+      verifyingBody: "No credential is submitted. The outcome follows the selected catalog compatibility level.",
+      resultLabel: "Example outcome",
+      reset: "Reset demo",
+      download: "Download OneAgent",
+      explore: "Open full Explorer",
+      security: "Release policy",
+      installed: "Installed",
+      notInstalled: "Not installed",
+      configured: "Configured",
+      needsSetup: "Needs setup",
+      officialGuide: "Official guide",
+      recommended: "Recommended path",
+      locked: "Locked",
+      noLockedVersion: "Official release",
+      command: "Launch",
+      managed: "Managed config",
+      guide: "Official setup",
+      facts: ["No device access", "No API key field", "Registry-derived compatibility"],
+      steps: ["Agent", "Setup", "Provider", "Model", "Confirm"],
+      modeTitle: "How should this agent be configured?",
+      modeBody: "OneAgent can point the agent at a model service, or leave an account you already use in place.",
+      modeProvider: "Configure a model service",
+      modeProviderHint: "Choose a provider or your own endpoint, then verify the protocol before anything is written.",
+      modeExisting: "Keep an existing account or config",
+      modeExistingHint: "Already signed in, or already configured? The provider and model steps are skipped.",
+      customName: "Custom endpoint",
+      customVerdict: "Your own OpenAI-compatible URL",
+      customLabel: "Base URL",
+      customPlaceholder: "https://api.example.com/openai",
+      customHint: "Any OpenAI-compatible endpoint. Validated the same way the app validates it.",
+      register: "Need a key? Open PPIO",
+      registerNote: "Opens ppio.com in a new tab. OneAgent has no account of its own.",
+      urlRequired: "Enter a base URL.",
+      urlScheme: "Must start with http:// or https://",
+      urlCredentials: "Remove the username or password from the URL.",
+      urlControl: "Remove control characters from the URL.",
+      urlOk: "Endpoint accepted",
+      modelTitle: "Choose a model",
+      modelBody: "The app reads this list from the endpoint itself. Pick one, or type an id if discovery comes back empty.",
+      modelManual: "Discovery empty? Enter an id",
+      modelManualLabel: "Model id",
+      confirm: "Confirm activation",
+      skipped: "Skipped",
+      /* The real window's sidebar is a workspace nav, not a progress list — the
+         stepper lives in the page header. These are its actual four entries. */
+      navItems: ["Activate", "Overview", "Providers", "Templates"],
+      sidebarNote: "Configuration stays on this machine",
+      footerIdle: "The demo never touches this device",
+      chineseOnly: "in Chinese",
+    }
+  : {
+      label: "可操作的产品证据",
+      sample: "示例环境",
+      title: "激活控制台",
+      subtitle: "这是引导演示。页面不会扫描你的设备，也不会要求输入 API Key。",
+      idleTitle: "等待你启动演示。",
+      idleBody: "从首屏主按钮开始，OneAgent 将演示一次完整激活路径，但不会访问这台电脑。",
+      scanningTitle: "正在扫描示例环境",
+      scanningBody: "读取确定性的演示场景，不读取浏览器、本机文件或本地服务。",
+      agentTitle: "选择一个 Agent",
+      agentBody: "能力与锁定版本来自仓库目录；安装和配置状态明确属于示例。",
+      providerTitle: "选择一个 Provider",
+      providerBody: "兼容结果来自协议注册表；预览门禁不会被升级成 Ready。",
+      verify: "验证示例连接",
+      verifyingTitle: "正在验证示例协议",
+      verifyingBody: "不会提交任何凭证；结果严格跟随所选组合的兼容等级。",
+      resultLabel: "示例结果",
+      reset: "重置演示",
+      download: "下载 OneAgent",
+      explore: "打开完整配置目录",
+      security: "发行政策",
+      installed: "已安装",
+      notInstalled: "未安装",
+      configured: "已配置",
+      needsSetup: "待配置",
+      officialGuide: "官方引导",
+      recommended: "推荐路径",
+      locked: "锁定版本",
+      noLockedVersion: "官方发行",
+      command: "启动命令",
+      managed: "托管配置",
+      guide: "官方设置",
+      facts: ["不访问设备", "不提供 Key 输入框", "兼容结论来自注册表"],
+      steps: ["Agent", "配置", "Provider", "模型", "确认"],
+      modeTitle: "这个 Agent 怎么配置？",
+      modeBody: "可以由 OneAgent 指向某个模型服务，也可以保留你已经在用的账号。",
+      modeProvider: "配置模型服务",
+      modeProviderHint: "选择 Provider 或你自己的端点，写入前先验证协议。",
+      modeExisting: "使用已有账号或配置",
+      modeExistingHint: "已经登录、或已经配置好？Provider 与模型两步会跳过。",
+      customName: "自定义端点",
+      customVerdict: "你自己的 OpenAI 兼容地址",
+      customLabel: "Base URL",
+      customPlaceholder: "https://api.example.com/openai",
+      customHint: "任何 OpenAI 兼容端点。校验规则与应用内一致。",
+      register: "还没有 Key？打开 PPIO",
+      registerNote: "在新标签页打开 ppio.com。OneAgent 自身没有账号体系。",
+      urlRequired: "请填写 Base URL。",
+      urlScheme: "需要以 http:// 或 https:// 开头。",
+      urlCredentials: "请从地址中去掉用户名或密码。",
+      urlControl: "请去掉地址中的控制字符。",
+      urlOk: "端点可用",
+      modelTitle: "选择模型",
+      modelBody: "应用会从端点自身读取这个列表。选一个，或在发现结果为空时手动输入 ID。",
+      modelManual: "列表为空？手动输入 ID",
+      modelManualLabel: "模型 ID",
+      confirm: "确认激活",
+      skipped: "已跳过",
+      /* The real window's sidebar is a workspace nav, not a progress list — the
+         stepper lives in the page header. These are its actual four entries. */
+      navItems: ["激活环境", "环境总览", "Provider", "配置模板"],
+      sidebarNote: "配置只保存在本机",
+      footerIdle: "演示不会访问这台设备",
+      chineseOnly: "仅中文",
+    };
+---
+<div class="product-shot activation-shell">
+  <activation-console id={id} data-locale={locale} data-phase="idle">
+    <div class="activation-window" tabindex="-1" data-console-window>
+      <header class="activation-topbar">
+        <div>
+          <span class="activation-kicker">{copy.label}</span>
+          <strong>{copy.title}</strong>
+        </div>
+        <span class="activation-sample"><span aria-hidden="true"></span>{copy.sample}</span>
+      </header>
+
+      <div class="activation-body">
+        <aside class="activation-rail" aria-label={locale === "en" ? "Workspace" : "工作区"}>
+          <div class="activation-rail-brand">
+            <span class="activation-monogram" aria-hidden="true">OA</span>
+            <div><strong>OneAgent</strong><span>{copy.sample}</span></div>
+          </div>
+          {/* Presentational: the real sidebar navigates a workspace, but nothing
+              here is navigable, so these are not links or buttons. */}
+          <div class="activation-nav" aria-hidden="true">
+            {copy.navItems.map((item, index) => (
+              <span class:list={["activation-nav-item", { "is-active": index === 0 }]}>{item}</span>
+            ))}
+          </div>
+          <p class="activation-rail-note">{copy.sidebarNote}</p>
+        </aside>
+
+        <div class="activation-main">
+          <div class="activation-heading">
+            <div>
+              <span class="activation-state-label" data-state-label>{copy.sample}</span>
+              <h2>{copy.title}</h2>
+              <p class="activation-subtitle">{copy.subtitle}</p>
+            </div>
+            <span class="activation-status" data-status><span aria-hidden="true"></span><b>Idle</b></span>
+          </div>
+          <ol class="activation-steps">
+            {copy.steps.map((step, index) => (
+              <li data-step={index + 1}>
+                <span class="activation-step-marker">{index + 1}</span>
+                <strong>{step}</strong>
+              </li>
+            ))}
+          </ol>
+
+          <section class="activation-panel" data-panel="idle" tabindex="-1">
+            <div class="activation-empty-mark" aria-hidden="true"><span></span><span></span><span></span></div>
+            <div>
+              <h3>{copy.idleTitle}</h3>
+              <p>{copy.idleBody}</p>
+            </div>
+          </section>
+
+          <section class="activation-panel activation-progress" data-panel="scanning" tabindex="-1" hidden>
+            <div class="activation-scan" aria-hidden="true"><span></span></div>
+            <div>
+              <h3>{copy.scanningTitle}</h3>
+              <p>{copy.scanningBody}</p>
+            </div>
+          </section>
+
+          <section class="activation-panel activation-choice-panel" data-panel="agent" tabindex="-1" hidden>
+            <div class="activation-panel-copy">
+              <h3>{copy.agentTitle}</h3>
+              <p>{copy.agentBody}</p>
+            </div>
+            <div class="activation-agent-grid" role="group" aria-label={copy.agentTitle}>
+              {featuredAgents.map((agent) => {
+                const demo = demoStateFor(agent);
+                return (
+                  <button
+                    type="button"
+                    class="activation-agent"
+                    data-agent-id={agent.id}
+                    aria-pressed="false"
+                  >
+                    <AgentMark id={agent.id} name={agent.name} size={28} />
+                    <span class="activation-agent-copy">
+                      <strong>{agent.name}</strong>
+                      <small>
+                        {demo.installed ? copy.installed : copy.notInstalled}
+                        {agent.lockedVersion ? ` · ${copy.locked} ${agent.lockedVersion}` : ` · ${copy.noLockedVersion}`}
+                      </small>
+                    </span>
+                    <span class:list={["activation-agent-state", `is-${demo.status}`]}>
+                      {agent.support.officialInstallGuide ? copy.officialGuide : demo.configured ? copy.configured : copy.needsSetup}
+                    </span>
+                    {recommendation?.agentId === agent.id && <span class="activation-recommended">{copy.recommended}</span>}
+                  </button>
+                );
+              })}
+            </div>
+          </section>
+
+          <section class="activation-panel activation-choice-panel" data-panel="mode" tabindex="-1" hidden>
+            <div class="activation-panel-copy">
+              <h3>{copy.modeTitle}</h3>
+              <p>{copy.modeBody}</p>
+            </div>
+            <div class="activation-mode-grid" role="group" aria-label={copy.modeTitle}>
+              <button type="button" class="activation-mode" data-mode="provider" aria-pressed="false">
+                <strong>{copy.modeProvider}</strong>
+                <small>{copy.modeProviderHint}</small>
+              </button>
+              <button type="button" class="activation-mode" data-mode="existing-account" aria-pressed="false">
+                <strong>{copy.modeExisting}</strong>
+                <small>{copy.modeExistingHint}</small>
+              </button>
+            </div>
+          </section>
+
+          <section class="activation-panel activation-choice-panel" data-panel="provider" tabindex="-1" hidden>
+            <div class="activation-panel-copy">
+              <h3>{copy.providerTitle}</h3>
+              <p>{copy.providerBody}</p>
+            </div>
+            <div class="activation-selection-line">
+              <span data-selected-agent>—</span>
+              <span aria-hidden="true">→</span>
+              <span data-selected-protocol>—</span>
+            </div>
+            <div class="activation-provider-grid" role="group" aria-label={copy.providerTitle}>
+              {catalog.providers.map((provider) => (
+                <button type="button" class="activation-provider" data-provider-id={provider.id} aria-pressed="false">
+                  <span><strong>{provider.name}</strong><small data-provider-verdict>—</small></span>
+                  <span class="activation-provider-arrow" aria-hidden="true">↗</span>
+                </button>
+              ))}
+              <button type="button" class="activation-provider is-custom" data-provider-id="custom" aria-pressed="false">
+                <span><strong>{copy.customName}</strong><small>{copy.customVerdict}</small></span>
+                <span class="activation-provider-arrow" aria-hidden="true">+</span>
+              </button>
+            </div>
+            <div class="activation-custom" data-custom-field hidden>
+              <label for={`${id}-base-url`}>{copy.customLabel}</label>
+              <input
+                id={`${id}-base-url`}
+                type="url"
+                inputmode="url"
+                autocomplete="off"
+                spellcheck="false"
+                placeholder={copy.customPlaceholder}
+                data-custom-input
+                aria-describedby={`${id}-base-url-hint`}
+              />
+              <p class="activation-custom-hint" id={`${id}-base-url-hint`} data-custom-hint data-idle={copy.customHint} data-kind="idle">{copy.customHint}</p>
+              <a class="activation-register" href="https://ppio.com/" target="_blank" rel="noopener noreferrer">
+                {copy.register}
+                <small>{copy.registerNote}</small>
+              </a>
+            </div>
+          </section>
+
+          <section class="activation-panel activation-choice-panel" data-panel="model" tabindex="-1" hidden>
+            <div class="activation-panel-copy">
+              <h3>{copy.modelTitle}</h3>
+              <p>{copy.modelBody}</p>
+            </div>
+            <div class="activation-model-grid" role="group" aria-label={copy.modelTitle} data-model-grid></div>
+            <details class="activation-manual">
+              <summary>{copy.modelManual}</summary>
+              <label for={`${id}-model-id`}>{copy.modelManualLabel}</label>
+              <input
+                id={`${id}-model-id`}
+                type="text"
+                autocomplete="off"
+                spellcheck="false"
+                placeholder={DEMO_CUSTOM_MODEL_HINT}
+                data-model-input
+              />
+            </details>
+          </section>
+
+          <section class="activation-panel activation-progress" data-panel="verifying" tabindex="-1" hidden>
+            <div class="activation-scan is-verify" aria-hidden="true"><span></span></div>
+            <div>
+              <h3>{copy.verifyingTitle}</h3>
+              <p>{copy.verifyingBody}</p>
+              <div class="activation-verifying-pair"><strong data-verifying-agent>—</strong><span>×</span><strong data-verifying-provider>—</strong></div>
+            </div>
+          </section>
+
+          <section class="activation-panel activation-result" data-panel="result" tabindex="-1" hidden>
+            <div class="activation-result-icon" aria-hidden="true" data-result-icon><svg viewBox="0 0 32 32"><path data-result-path d="M7 17l6 6L26 9"></path></svg></div>
+            <div>
+              <span class="activation-state-label">{copy.resultLabel}</span>
+              <h3 data-result-title>—</h3>
+              <p data-result-body>—</p>
+              <div class="activation-result-meta"><strong data-result-agent>—</strong><span>→</span><strong data-result-provider>—</strong></div>
+              <div class="activation-result-actions">
+                <a class="button button-primary" href={href("downloads/")} data-ready-action hidden>{copy.download}</a>
+                <a class="button button-secondary" href={href("explore/")} data-explore-action>{copy.explore}</a>
+                <a class="button button-text" href={href("security/")} data-security-action hidden>
+                  {copy.security}
+                  {switchesLanguage(locale, "security/") && <span class="lang-hint">{copy.chineseOnly}</span>}
+                </a>
+              </div>
+            </div>
+          </section>
+
+          <div class="activation-log-wrap">
+            <span>{locale === "en" ? "EVENT LOG" : "事件日志"}</span>
+            <ol class="activation-log" data-log aria-live="polite" aria-relevant="additions" tabindex="0" aria-label={locale === "en" ? "Activation demo event log" : "激活演示事件日志"}>
+              <li>{locale === "en" ? "Demo idle. No device access requested." : "演示待机，未请求设备访问。"}</li>
+            </ol>
+          </div>
+        </div>
+
+        {/* The real window keeps its primary action in a fixed footer bar rather
+            than inside the scrolling body, so the next step is always in the same
+            place. The note on the left is where the app puts its own context. */}
+        <footer class="activation-footer">
+          <p class="activation-footer-note" data-footer-note>{copy.footerIdle}</p>
+          <div class="activation-footer-actions">
+            <button class="activation-reset" type="button" data-reset hidden>{copy.reset}</button>
+            <button class="button button-small button-primary" type="button" data-verify hidden disabled>{copy.verify}</button>
+            <button class="button button-small button-primary" type="button" data-confirm hidden disabled>{copy.confirm}</button>
+          </div>
+        </footer>
+      </div>
+
+      <footer class="activation-facts">
+        {copy.facts.map((fact) => <span><i aria-hidden="true"></i>{fact}</span>)}
+      </footer>
+    </div>
+  </activation-console>
+</div>
+
+<script>
+  import { catalog } from "../lib/catalog";
+  import {
+    CUSTOM_PROVIDER_ID,
+    activationReducer,
+    initialActivationState,
+    validateDemoBaseUrl,
+    type ActivationState,
+    type ConfigMode,
+  } from "../lib/activation";
+  import { demoModelsFor } from "../lib/demo-environment";
+  import { compatibilityFor, recommendedCombination } from "../lib/explorer";
+
+
+  const messages = {
+    "zh-CN": {
+      status: {
+        idle: "待机",
+        scanning: "扫描示例",
+        agent: "选择 Agent",
+        mode: "配置方式",
+        provider: "选择 Provider",
+        model: "选择模型",
+        verifying: "验证示例",
+        ready: "Ready",
+        "guide-only": "官方引导",
+        "preview-gate": "预览门禁",
+        unsupported: "不兼容",
+        error: "演示错误",
+      },
+      log: {
+        scanning: "开始扫描示例环境；未访问本机。",
+        scanned: "示例扫描完成，可以选择 Agent。",
+        agent: (name: string) => `已选择 ${name}。`,
+        guide: (name: string) => `${name} 需要使用官方设置流程。`,
+        modeProvider: "将由 OneAgent 配置模型服务。",
+        modeExisting: "沿用已有账号或配置；Provider 与模型步骤已跳过。",
+        provider: (name: string, verdict: string) => `已选择 ${name}：${verdict}。`,
+        custom: "已选择自定义端点；地址通过与应用一致的校验后才能验证。",
+        customRejected: (reason: string) => `端点未通过校验：${reason}`,
+        customAccepted: (url: string) => `端点校验通过：${url}`,
+        verifying: "开始验证示例连接；未提交任何凭证。",
+        verified: "示例协议验证完成，可以选择模型。",
+        models: (count: number) => `端点返回 ${count} 个示例模型。`,
+        model: (id: string) => `已选择模型 ${id}。`,
+        ready: "示例环境可进入 Ready。",
+        preview: "连接路径可演示，但公开状态仍要求发布候选验证。",
+        unsupported: "所选 Provider 不支持该 Agent 所需协议。",
+        error: "演示状态无效，请重置后重试。",
+      },
+      compatibility: {
+        verified: "注册表已验证",
+        supported: "实现支持",
+        "preview-gate": "需要发布候选验证",
+        unsupported: "协议不兼容",
+      },
+      result: {
+        ready: ["示例环境已 Ready", "所选组合可按当前实现路径完成配置与协议验证。真实激活将在本地 OneAgent 中完成。"],
+        existing: ["保留现有账号", "OneAgent 只把这个 Agent 标记为已就绪，不改动它现有的登录状态，也不写入新的凭证。"],
+        guide: ["转入官方设置", "这个 Agent 不由 OneAgent 写入私有配置。请按官方方式安装或登录，再回到 OneAgent 查看环境。"],
+        preview: ["仍需通过发布门禁", "示例连接可以继续，但该协议组合仍标记为需要发布候选验证，因此不会被宣称为 Ready。"],
+        unsupported: ["协议组合不兼容", "请返回并选择支持该 Agent 协议的 Provider。OneAgent 不会静默降级到其他协议。"],
+        error: ["演示无法继续", "状态不完整或目录发生变化。请重置演示后重新选择。"],
+      },
+      protocol: { openai: "Chat Completions", anthropic: "Anthropic Messages", responses: "OpenAI Responses" },
+      url: {
+        required: "请填写 Base URL。",
+        scheme: "需要以 http:// 或 https:// 开头。",
+        credentials: "请从地址中去掉用户名或密码。",
+        "control-characters": "请去掉地址中的控制字符。",
+        ok: "端点可用",
+      },
+      skipped: "已跳过",
+      /* The app puts step context in the footer bar next to the action. */
+      footer: {
+        idle: "演示不会访问这台设备",
+        scanning: "正在读取示例环境",
+        agent: "从上面选一个 Agent",
+        mode: "选择配置方式",
+        provider: "选择 Provider 或填入你自己的端点",
+        model: "选择一个模型后确认",
+        verifying: "正在验证，未提交凭证",
+        ready: "示例流程已完成",
+        "guide-only": "这个 Agent 走官方流程",
+        "preview-gate": "组合可演示，但未通过发布门禁",
+        unsupported: "请换一个支持该协议的 Provider",
+        error: "请重置演示后重试",
+      },
+    },
+    en: {
+      status: {
+        idle: "Idle",
+        scanning: "Scanning demo",
+        agent: "Choose agent",
+        mode: "Setup",
+        provider: "Choose provider",
+        model: "Choose model",
+        verifying: "Verifying demo",
+        ready: "Ready",
+        "guide-only": "Official guide",
+        "preview-gate": "Preview gate",
+        unsupported: "Unsupported",
+        error: "Demo error",
+      },
+      log: {
+        scanning: "Started scanning the example environment; no device access requested.",
+        scanned: "Example scan complete. Choose an agent.",
+        agent: (name: string) => `Selected ${name}.`,
+        guide: (name: string) => `${name} uses its official setup flow.`,
+        modeProvider: "OneAgent will configure a model service.",
+        modeExisting: "Keeping the existing account or config; provider and model steps skipped.",
+        provider: (name: string, verdict: string) => `Selected ${name}: ${verdict}.`,
+        custom: "Selected a custom endpoint. The URL is validated the same way the app validates it.",
+        customRejected: (reason: string) => `Endpoint rejected: ${reason}`,
+        customAccepted: (url: string) => `Endpoint accepted: ${url}`,
+        verifying: "Started sample verification; no credential was submitted.",
+        verified: "Sample protocol verification completed. Choose a model.",
+        models: (count: number) => `The endpoint returned ${count} example models.`,
+        model: (id: string) => `Selected model ${id}.`,
+        ready: "The example environment may reach Ready.",
+        preview: "The path can be demonstrated, but the public status still requires release-candidate verification.",
+        unsupported: "The selected provider does not support the protocol this agent requires.",
+        error: "The demo state is invalid. Reset and try again.",
+      },
+      compatibility: {
+        verified: "Registry verified",
+        supported: "Implementation supported",
+        "preview-gate": "Release candidate required",
+        unsupported: "Protocol incompatible",
+      },
+      result: {
+        ready: ["Example environment is Ready", "This combination can follow the current configuration and protocol-verification path. Real activation happens in the local OneAgent app."],
+        existing: ["Existing account kept", "OneAgent marks this agent ready without touching its current sign-in or writing a new credential."],
+        guide: ["Continue with official setup", "OneAgent does not write private configuration for this agent. Install or sign in through the official flow, then return to review the environment."],
+        preview: ["A release gate remains", "The sample path can continue, but this protocol combination still requires release-candidate verification and is not presented as Ready."],
+        unsupported: ["Protocol combination unsupported", "Go back and choose a provider that supports the agent protocol. OneAgent never silently falls back to another protocol."],
+        error: ["The demo cannot continue", "The selection is incomplete or the catalog changed. Reset the demo and choose again."],
+      },
+      protocol: { openai: "Chat Completions", anthropic: "Anthropic Messages", responses: "OpenAI Responses" },
+      url: {
+        required: "Enter a base URL.",
+        scheme: "Must start with http:// or https://",
+        credentials: "Remove the username or password from the URL.",
+        "control-characters": "Remove control characters from the URL.",
+        ok: "Endpoint accepted",
+      },
+      skipped: "Skipped",
+      /* The app puts step context in the footer bar next to the action. */
+      footer: {
+        idle: "The demo never touches this device",
+        scanning: "Reading the example environment",
+        agent: "Choose an agent above",
+        mode: "Choose how to configure it",
+        provider: "Choose a provider, or enter your own endpoint",
+        model: "Choose a model, then confirm",
+        verifying: "Verifying — no credential submitted",
+        ready: "The example flow is complete",
+        "guide-only": "This agent uses its official flow",
+        "preview-gate": "Demonstrable, but the release gate remains",
+        unsupported: "Choose a provider that supports this protocol",
+        error: "Reset the demo and try again",
+      },
+    },
+  } as const;
+
+  /* The unattended walkthrough. Selection steps get a beat long enough to read
+     the panel that just appeared; the two probe steps reuse the timings the
+     manual path already uses, so an autoplayed run and a clicked one look the
+     same rather than one feeling rushed. */
+  type AutoplayStep = { delay: number; run: (element: ActivationConsoleElement) => void };
+  const AUTOPLAY_SCRIPT: AutoplayStep[] = [
+    { delay: 420, run: (element) => element.start() },
+    { delay: 1500, run: (element) => element.selectAgent("claude-code") },
+    { delay: 900, run: (element) => element.selectMode("provider") },
+    { delay: 900, run: (element) => element.selectProvider("ppio") },
+    { delay: 900, run: (element) => element.verify() },
+    { delay: 1100, run: (element) => element.selectModel(element.models[0] ?? "", false) },
+    { delay: 900, run: (element) => element.confirm() },
+  ];
+
+  class ActivationConsoleElement extends HTMLElement {
+    state: ActivationState = initialActivationState();
+    timer: number | null = null;
+    abort = new AbortController();
+    /* Autoplay owns the state machine only until the visitor touches it. Both
+       flags are one-way: `autoplaying` suppresses the focus and scroll side
+       effects that would hijack the page, and `autoplayDone` makes takeover and
+       completion permanent so nothing re-arms behind the visitor's back. */
+    autoplaying = false;
+    autoplayDone = false;
+    autoplayTimer: number | null = null;
+    observer: IntersectionObserver | null = null;
+
+    connectedCallback() {
+      if (this.dataset.initialized === "true") return;
+      this.dataset.initialized = "true";
+      const signal = this.abort.signal;
+      this.querySelectorAll<HTMLButtonElement>("[data-agent-id]").forEach((button) => {
+        button.addEventListener("click", () => this.selectAgent(button.dataset.agentId || ""), { signal });
+      });
+      this.querySelectorAll<HTMLButtonElement>("[data-mode]").forEach((button) => {
+        button.addEventListener("click", () => this.selectMode(button.dataset.mode as ConfigMode), { signal });
+      });
+      this.querySelectorAll<HTMLButtonElement>("[data-provider-id]").forEach((button) => {
+        button.addEventListener("click", () => this.selectProvider(button.dataset.providerId || ""), { signal });
+      });
+      this.querySelector<HTMLInputElement>("[data-custom-input]")?.addEventListener("input", (event) => {
+        this.setCustomBaseUrl((event.currentTarget as HTMLInputElement).value);
+      }, { signal });
+      this.querySelector<HTMLInputElement>("[data-model-input]")?.addEventListener("input", (event) => {
+        this.selectModel((event.currentTarget as HTMLInputElement).value.trim(), false);
+      }, { signal });
+      this.querySelector<HTMLButtonElement>("[data-confirm]")?.addEventListener("click", () => this.confirm(), { signal });
+      this.querySelector<HTMLButtonElement>("[data-verify]")?.addEventListener("click", () => this.verify(), { signal });
+      this.querySelector<HTMLButtonElement>("[data-reset]")?.addEventListener("click", () => this.reset(), { signal });
+      document.querySelectorAll<HTMLButtonElement>(`[data-activation-trigger="${this.id}"]`).forEach((button) => {
+        // The trigger sits in the hero, outside this element, so it misses the
+        // takeover listeners below. Pressing it is the clearest takeover there
+        // is: after autoplay has run it is the replay entry.
+        button.addEventListener("click", () => {
+          this.cancelAutoplay();
+          this.start();
+        }, { signal });
+      });
+      /* Any of the three means the visitor is driving. They are captured on the
+         way down so takeover is recorded before the click handler above runs its
+         own step, and they cover the keyboard and screen-reader paths that never
+         produce a pointer event. */
+      for (const type of ["pointerdown", "keydown", "focusin"] as const) {
+        this.addEventListener(type, () => this.cancelAutoplay(), { signal, capture: true });
+      }
+      this.render();
+      this.armAutoplay();
+    }
+
+    disconnectedCallback() {
+      if (this.timer !== null) window.clearTimeout(this.timer);
+      if (this.autoplayTimer !== null) window.clearTimeout(this.autoplayTimer);
+      this.observer?.disconnect();
+      this.abort.abort();
+    }
+
+    /* Autoplay waits for the console to be half on screen: running it on load
+       would finish before a visitor scrolling down ever saw it. Reduced motion
+       opts out entirely — advancing the interface on its own is motion, and the
+       manual trigger still works.  */
+    armAutoplay() {
+      if (this.reducedMotion || this.dataset.autoplay === "off") return;
+      if (typeof IntersectionObserver !== "function") return;
+      this.observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+          if (!entry.isIntersecting) continue;
+          this.observer?.disconnect();
+          this.observer = null;
+          this.startAutoplay();
+        }
+      }, { threshold: 0.5 });
+      this.observer.observe(this);
+    }
+
+    startAutoplay() {
+      if (this.autoplayDone || this.state.phase !== "idle") return;
+      this.autoplaying = true;
+      this.dataset.autoplaying = "true";
+      this.queueAutoplay(0);
+    }
+
+    queueAutoplay(index: number) {
+      const step = AUTOPLAY_SCRIPT[index];
+      if (!step) return this.finishAutoplay();
+      this.autoplayTimer = window.setTimeout(() => {
+        this.autoplayTimer = null;
+        if (!this.autoplaying) return;
+        step.run(this);
+        // A step that lands somewhere the script did not plan for — a catalog
+        // change turning the combination into a gate — stops here rather than
+        // dispatching actions the reducer would reject.
+        if (!this.autoplaying) return;
+        this.queueAutoplay(index + 1);
+      }, step.delay);
+    }
+
+    /** Autoplay reached the end on its own: stop, and never re-arm. */
+    finishAutoplay() {
+      this.autoplaying = false;
+      this.autoplayDone = true;
+      delete this.dataset.autoplaying;
+    }
+
+    /** The visitor took over. Whatever step is showing is where it stays. */
+    cancelAutoplay() {
+      this.observer?.disconnect();
+      this.observer = null;
+      if (this.autoplayTimer !== null) window.clearTimeout(this.autoplayTimer);
+      this.autoplayTimer = null;
+      this.autoplaying = false;
+      this.autoplayDone = true;
+      delete this.dataset.autoplaying;
+    }
+
+    get locale() {
+      return this.dataset.locale === "en" ? "en" : "zh-CN";
+    }
+
+    get copy() {
+      return messages[this.locale];
+    }
+
+    get reducedMotion() {
+      return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    }
+
+    dispatch(action: Parameters<typeof activationReducer>[1]) {
+      this.state = activationReducer(this.state, action, catalog);
+      this.render();
+    }
+
+    start() {
+      if (this.state.phase !== "idle") this.reset(false);
+      this.dispatch({ type: "start" });
+      this.replaceLog(this.copy.log.scanning);
+      // Autoplay only begins once the console is already half on screen, so
+      // scrolling it to centre would move the page out from under a reader who
+      // asked for nothing.
+      if (!this.autoplaying) this.scrollIntoView({ behavior: this.reducedMotion ? "auto" : "smooth", block: "center" });
+      this.focusPanel("scanning");
+      this.timer = window.setTimeout(() => {
+        this.dispatch({ type: "scan-complete" });
+        this.appendLog(this.copy.log.scanned);
+        this.focusPanel("agent");
+      }, this.reducedMotion ? 0 : 650);
+    }
+
+    reset(focus = true) {
+      if (this.timer !== null) window.clearTimeout(this.timer);
+      this.timer = null;
+      this.dispatch({ type: "reset" });
+      this.replaceLog(this.locale === "en" ? "Demo idle. No device access requested." : "演示待机，未请求设备访问。");
+      if (focus) this.focusPanel("idle");
+    }
+
+    selectAgent(agentId: string) {
+      const agent = catalog.agents.find((candidate) => candidate.id === agentId);
+      if (!agent) return this.fail();
+      this.dispatch({ type: "select-agent", agentId });
+      this.appendLog(this.copy.log.agent(agent.name));
+      if (this.state.phase === "guide-only") {
+        this.appendLog(this.copy.log.guide(agent.name));
+        this.focusPanel("result");
+      } else {
+        this.updateProviders(agentId);
+        this.focusPanel("mode");
+      }
+    }
+
+    selectMode(mode: ConfigMode) {
+      if (mode !== "provider" && mode !== "existing-account") return this.fail();
+      this.dispatch({ type: "select-mode", mode });
+      if (this.state.phase === "ready") {
+        this.appendLog(this.copy.log.modeExisting);
+        this.focusPanel("result");
+        return;
+      }
+      this.appendLog(this.copy.log.modeProvider);
+      this.focusPanel("provider");
+    }
+
+    selectProvider(providerId: string) {
+      if (providerId === CUSTOM_PROVIDER_ID) {
+        this.dispatch({ type: "select-provider", providerId });
+        this.appendLog(this.copy.log.custom);
+        this.querySelector<HTMLInputElement>("[data-custom-input]")?.focus();
+        return;
+      }
+      const provider = catalog.providers.find((candidate) => candidate.id === providerId);
+      if (!provider) return this.fail();
+      this.dispatch({ type: "select-provider", providerId });
+      const verdict = this.state.compatibility ? this.copy.compatibility[this.state.compatibility] : this.copy.compatibility.unsupported;
+      this.appendLog(this.copy.log.provider(provider.name, verdict));
+      if (this.state.phase === "unsupported") {
+        this.appendLog(this.copy.log.unsupported);
+        this.focusPanel("result");
+      }
+    }
+
+    setCustomBaseUrl(value: string) {
+      this.dispatch({ type: "set-custom-base-url", value });
+    }
+
+    selectModel(model: string, fromList = true) {
+      if (!model) return;
+      this.dispatch({ type: "select-model", model });
+      if (this.state.model === model) this.appendLog(this.copy.log.model(model));
+      if (fromList) this.querySelector<HTMLButtonElement>("[data-confirm]")?.focus();
+    }
+
+    confirm() {
+      this.dispatch({ type: "confirm" });
+      if (this.state.phase !== "ready") return;
+      this.appendLog(this.copy.log.ready);
+      this.focusPanel("result");
+    }
+
+    verify() {
+      const before = this.state.phase;
+      this.dispatch({ type: "verify" });
+      if (this.state.phase === "error") return this.fail(false);
+      // A rejected endpoint leaves the phase untouched rather than erroring, the
+      // same non-event as the product's disabled probe button.
+      if (this.state.phase === before) return;
+      this.appendLog(this.copy.log.verifying);
+      this.focusPanel("verifying");
+      this.timer = window.setTimeout(() => {
+        this.dispatch({ type: "verify-complete" });
+        if (this.state.phase === "model") {
+          this.appendLog(this.copy.log.verified);
+          this.renderModels();
+          this.appendLog(this.copy.log.models(this.models.length));
+          this.focusPanel("model");
+          return;
+        }
+        if (this.state.phase === "preview-gate") this.appendLog(this.copy.log.preview);
+        this.focusPanel("result");
+      }, this.reducedMotion ? 0 : 700);
+    }
+
+    get models() {
+      return this.state.providerId === CUSTOM_PROVIDER_ID ? [] : demoModelsFor(this.state.providerId);
+    }
+
+    footerNoteFor(phase: ActivationState["phase"]) {
+      return this.copy.footer[phase];
+    }
+
+    customHost() {
+      const check = validateDemoBaseUrl(this.state.customBaseUrl);
+      if (!check.ok) return "";
+      try {
+        return new URL(check.value).host;
+      } catch {
+        return "";
+      }
+    }
+
+    renderModels() {
+      const grid = this.querySelector<HTMLElement>("[data-model-grid]");
+      if (!grid) return;
+      grid.replaceChildren();
+      for (const model of this.models) {
+        const button = document.createElement("button");
+        button.type = "button";
+        button.className = "activation-model";
+        button.dataset.model = model;
+        button.setAttribute("aria-pressed", "false");
+        button.textContent = model;
+        button.addEventListener("click", () => this.selectModel(model), { signal: this.abort.signal });
+        grid.append(button);
+      }
+      // A custom endpoint publishes no list, so the manual entry is the path
+      // rather than a fallback — open it instead of showing an empty group.
+      const manual = this.querySelector<HTMLDetailsElement>(".activation-manual");
+      if (manual) manual.open = this.models.length === 0;
+      grid.hidden = this.models.length === 0;
+    }
+
+    fail(dispatch = true) {
+      if (dispatch) this.dispatch({ type: "fail" });
+      this.appendLog(this.copy.log.error);
+      this.focusPanel("result");
+    }
+
+    updateProviders(agentId: string) {
+      const agent = catalog.agents.find((candidate) => candidate.id === agentId);
+      if (!agent) return;
+      const recommendation = recommendedCombination(catalog);
+      this.querySelectorAll<HTMLButtonElement>("[data-provider-id]").forEach((button) => {
+        const provider = catalog.providers.find((candidate) => candidate.id === button.dataset.providerId);
+        if (!provider) return;
+        const compatibility = compatibilityFor(agent, provider);
+        button.dataset.compatibility = compatibility;
+        button.classList.toggle("is-recommended", recommendation?.agentId === agent.id && recommendation.providerId === provider.id);
+        const verdict = button.querySelector<HTMLElement>("[data-provider-verdict]");
+        if (verdict) verdict.textContent = this.copy.compatibility[compatibility];
+        button.setAttribute("aria-label", `${provider.name}: ${this.copy.compatibility[compatibility]}`);
+      });
+    }
+
+    replaceLog(message: string) {
+      const log = this.querySelector<HTMLOListElement>("[data-log]");
+      if (!log) return;
+      log.replaceChildren();
+      this.appendLog(message);
+    }
+
+    appendLog(message: string) {
+      const log = this.querySelector<HTMLOListElement>("[data-log]");
+      if (!log) return;
+      const item = document.createElement("li");
+      item.textContent = message;
+      log.append(item);
+      log.scrollTop = log.scrollHeight;
+    }
+
+    /* Moving focus is right when the visitor asked for the step — it carries a
+       keyboard user forward. During autoplay nobody asked, so taking focus would
+       pull it out of whatever they were reading or tabbing through. The panels
+       stay an aria-live region either way, so the steps are still announced. */
+    focusPanel(name: string) {
+      if (this.autoplaying) return;
+      window.requestAnimationFrame(() => this.querySelector<HTMLElement>(`[data-panel="${name}"]`)?.focus({ preventScroll: true }));
+    }
+
+    render() {
+      const phase = this.state.phase;
+      this.dataset.phase = phase;
+      const panel = ["idle", "scanning", "agent", "mode", "provider", "model", "verifying"].includes(phase) ? phase : "result";
+      this.querySelectorAll<HTMLElement>("[data-panel]").forEach((element) => {
+        element.hidden = element.dataset.panel !== panel;
+      });
+
+      const status = this.querySelector<HTMLElement>("[data-status]");
+      if (status) {
+        status.dataset.kind = phase;
+        const label = status.querySelector("b");
+        if (label) label.textContent = this.copy.status[phase];
+      }
+      const reset = this.querySelector<HTMLButtonElement>("[data-reset]");
+      if (reset) reset.hidden = phase === "idle";
+
+      /* Steps mirror the product's stepper: Agent, Setup, Provider, Model, Confirm.
+         Choosing an existing account skips 3 and 4, so those are marked skipped
+         rather than done — the product labels them the same way. */
+      const stepOf: Partial<Record<typeof phase, number>> = {
+        idle: 0,
+        scanning: 1,
+        agent: 1,
+        "guide-only": 1,
+        mode: 2,
+        provider: 3,
+        verifying: 3,
+        unsupported: 3,
+        "preview-gate": 3,
+        model: 4,
+        ready: 5,
+      };
+      const current = stepOf[phase] ?? 5;
+      const skipped = this.state.configMode === "existing-account";
+      this.querySelectorAll<HTMLElement>("[data-step]").forEach((step) => {
+        const index = Number(step.dataset.step || 0);
+        const isSkipped = skipped && (index === 3 || index === 4);
+        step.classList.toggle("is-current", index === current && !isSkipped);
+        step.classList.toggle("is-done", !isSkipped && (current > index || phase === "ready"));
+        step.classList.toggle("is-skipped", isSkipped);
+        if (index === current && !isSkipped) step.setAttribute("aria-current", "step");
+        else step.removeAttribute("aria-current");
+      });
+
+      this.querySelectorAll<HTMLButtonElement>("[data-agent-id]").forEach((button) => {
+        button.setAttribute("aria-pressed", String(button.dataset.agentId === this.state.agentId));
+      });
+      this.querySelectorAll<HTMLButtonElement>("[data-provider-id]").forEach((button) => {
+        button.setAttribute("aria-pressed", String(button.dataset.providerId === this.state.providerId));
+      });
+
+      const agent = catalog.agents.find((candidate) => candidate.id === this.state.agentId) ?? null;
+      const provider = catalog.providers.find((candidate) => candidate.id === this.state.providerId) ?? null;
+      this.querySelectorAll<HTMLElement>("[data-selected-agent], [data-verifying-agent], [data-result-agent]").forEach((element) => {
+        element.textContent = agent?.name ?? "—";
+      });
+      /* A custom endpoint has no catalog name, so it shows the host the visitor
+         typed — the specific thing they chose. An existing account has no
+         provider at all, which is the point, so it says so. */
+      const providerLabel = provider?.name
+        ?? (this.state.providerId === CUSTOM_PROVIDER_ID
+          ? this.customHost() || this.copy.status.provider
+          : this.state.configMode === "existing-account"
+            ? this.copy.skipped
+            : "—");
+      this.querySelectorAll<HTMLElement>("[data-verifying-provider], [data-result-provider]").forEach((element) => {
+        element.textContent = providerLabel;
+      });
+      const selectedProtocol = this.querySelector<HTMLElement>("[data-selected-protocol]");
+      if (selectedProtocol) selectedProtocol.textContent = agent?.protocol ? this.copy.protocol[agent.protocol] : "—";
+
+      this.querySelectorAll<HTMLButtonElement>("[data-mode]").forEach((button) => {
+        button.setAttribute("aria-pressed", String(button.dataset.mode === this.state.configMode));
+      });
+      this.querySelectorAll<HTMLButtonElement>("[data-model]").forEach((button) => {
+        button.setAttribute("aria-pressed", String(button.dataset.model === this.state.model));
+      });
+
+      const isCustom = this.state.providerId === CUSTOM_PROVIDER_ID;
+      const customField = this.querySelector<HTMLElement>("[data-custom-field]");
+      if (customField) customField.hidden = !isCustom;
+      const check = isCustom ? validateDemoBaseUrl(this.state.customBaseUrl) : null;
+      const customHint = this.querySelector<HTMLElement>("[data-custom-hint]");
+      const customInput = this.querySelector<HTMLInputElement>("[data-custom-input]");
+      if (customHint && customInput && check) {
+        // An empty field is the resting state, not an error to shout about.
+        const untouched = this.state.customBaseUrl === "";
+        customHint.textContent = untouched
+          ? customHint.dataset.idle || customHint.textContent
+          : check.ok
+            ? this.copy.url.ok
+            : this.copy.url[check.reason];
+        customHint.dataset.kind = untouched ? "idle" : check.ok ? "ok" : "error";
+        customInput.setAttribute("aria-invalid", String(!untouched && !check.ok));
+      }
+
+      /* Both primary actions live in the footer bar, so each is shown only on the
+         step it belongs to rather than moved between panels. */
+      const verify = this.querySelector<HTMLButtonElement>("[data-verify]");
+      if (verify) {
+        verify.hidden = phase !== "provider";
+        verify.disabled =
+          !this.state.providerId ||
+          this.state.compatibility === "unsupported" ||
+          (isCustom && !(check && check.ok));
+      }
+      const confirm = this.querySelector<HTMLButtonElement>("[data-confirm]");
+      if (confirm) {
+        confirm.hidden = phase !== "model";
+        confirm.disabled = !this.state.model;
+      }
+      const footerNote = this.querySelector<HTMLElement>("[data-footer-note]");
+      if (footerNote) footerNote.textContent = this.footerNoteFor(phase);
+
+      if (panel === "result") this.renderResult(phase);
+    }
+
+    renderResult(phase: ActivationState["phase"]) {
+      const title = this.querySelector<HTMLElement>("[data-result-title]");
+      const body = this.querySelector<HTMLElement>("[data-result-body]");
+      const icon = this.querySelector<HTMLElement>("[data-result-icon]");
+      const readyAction = this.querySelector<HTMLElement>("[data-ready-action]");
+      const securityAction = this.querySelector<HTMLElement>("[data-security-action]");
+      if (!title || !body || !icon || !readyAction || !securityAction) return;
+
+      const result = phase === "ready"
+        ? this.state.configMode === "existing-account"
+          ? this.copy.result.existing
+          : this.copy.result.ready
+        : phase === "guide-only"
+          ? this.copy.result.guide
+          : phase === "preview-gate"
+            ? this.copy.result.preview
+            : phase === "unsupported"
+              ? this.copy.result.unsupported
+              : this.copy.result.error;
+      title.textContent = result[0];
+      body.textContent = result[1];
+      const path = icon.querySelector<SVGPathElement>("[data-result-path]");
+      if (path) {
+        path.setAttribute(
+          "d",
+          phase === "ready"
+            ? "M7 17l6 6L26 9"
+            : phase === "guide-only"
+              ? "M8 24L24 8M13 8h11v11"
+              : phase === "preview-gate"
+                ? "M16 7v12M16 24v1"
+                : "M9 9l14 14M23 9L9 23",
+        );
+      }
+      icon.dataset.kind = phase;
+      readyAction.hidden = phase !== "ready";
+      securityAction.hidden = phase !== "preview-gate";
+    }
+  }
+
+  if (!customElements.get("activation-console")) {
+    customElements.define("activation-console", ActivationConsoleElement);
+  }
+</script>
+
+<style>
+  activation-console { display: block; }
+  .activation-shell { position: relative; z-index: 1; }
+  /* Geometry and colour measured off the running app (frontend/src/styles):
+     12px window radius, 52px title bar, 232px sidebar, 68px footer, and the
+     --shadow-window value verbatim. The app is light-only, so these use this
+     page's tokens rather than its hex values — that is the one difference. */
+  .activation-window {
+    overflow: hidden;
+    border: 1px solid var(--line-strong);
+    border-radius: var(--radius-window);
+    background: var(--surface);
+    color: var(--ink);
+    box-shadow: 0 22px 55px rgba(42, 42, 46, .16), 0 2px 8px rgba(42, 42, 46, .08);
+  }
+  .activation-topbar {
+    min-height: 52px;
+    padding: 0 18px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 20px;
+    border-bottom: 1px solid var(--line);
+    background: var(--surface-muted);
+  }
+  .activation-topbar > div { display: grid; gap: 2px; }
+  .activation-topbar strong { font-size: 14px; }
+  .activation-kicker, .activation-state-label {
+    color: var(--ink-faint);
+    font: 700 10px/1.2 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+    letter-spacing: .12em;
+    text-transform: uppercase;
+  }
+  .activation-sample, .activation-status {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    color: var(--ink-soft);
+    font-size: 12px;
+    font-weight: 650;
+  }
+  .activation-sample > span, .activation-status > span {
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    background: var(--orange);
+    box-shadow: 0 0 0 4px var(--orange-soft);
+  }
+  /* Two columns, two rows: the sidebar and body share the first row, and the
+     footer spans both so the primary action stays put while the body scrolls —
+     the same shape as the app's 232px/auto + content/68px grid. */
+  .activation-body {
+    min-height: 560px;
+    display: grid;
+    grid-template-columns: 232px minmax(0, 1fr);
+    grid-template-rows: minmax(0, 1fr) auto;
+  }
+  .activation-rail {
+    padding: 22px 12px 16px;
+    display: flex;
+    flex-direction: column;
+    color: var(--ink);
+    background: var(--surface-muted);
+    border-right: 1px solid var(--line);
+  }
+  /* Static labels, not controls — the demo has nowhere to navigate to. */
+  .activation-nav { display: grid; gap: 4px; }
+  .activation-nav-item {
+    min-height: 38px;
+    padding: 0 10px;
+    display: flex;
+    align-items: center;
+    border-radius: var(--radius-control);
+    color: var(--ink-soft);
+    font-size: 13px;
+  }
+  .activation-nav-item.is-active { background: var(--blue-deep); color: var(--on-accent); font-weight: 600; }
+  .activation-rail-note { margin-top: auto; padding: 12px 10px 0; color: var(--ink-faint); font-size: 11px; }
+  .activation-footer {
+    min-height: 68px;
+    padding: 0 42px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 20px;
+    grid-column: 1 / -1;
+    border-top: 1px solid var(--line);
+    background: var(--surface-muted);
+  }
+  .activation-footer-note { color: var(--ink-soft); font-size: 13px; }
+  .activation-footer-actions { display: flex; align-items: center; gap: 12px; }
+  .activation-rail-brand { padding: 0 10px 18px; display: flex; align-items: center; gap: 11px; }
+  .activation-rail-brand > div { display: grid; gap: 2px; }
+  .activation-rail-brand strong { font-size: 13px; }
+  /* Scoped to the subtitle rather than every span, so it cannot reach the
+     monogram — that one carries white on the accent fill and a broader
+     selector here would win on specificity and make it unreadable. */
+  .activation-rail-brand > div span { color: var(--ink-faint); font-size: 11px; }
+  .activation-monogram {
+    width: 26px;
+    height: 26px;
+    display: grid;
+    place-items: center;
+    border-radius: 7px;
+    color: var(--on-accent);
+    background: var(--blue-deep);
+    font: 750 10px/1 ui-monospace, SFMono-Regular, Menlo, monospace;
+    letter-spacing: .04em;
+  }
+  /* The app's stepper: a horizontal row in the page header, each step a 27px
+     numbered circle above an 11px label. Nothing is a card and nothing is dark. */
+  .activation-steps {
+    margin: 22px 0 0;
+    padding: 0;
+    display: grid;
+    grid-auto-flow: column;
+    grid-auto-columns: minmax(0, 124px);
+    justify-content: start;
+    list-style: none;
+  }
+  .activation-steps li { display: grid; gap: 5px; justify-items: start; color: var(--ink-faint); font-size: 11px; }
+  .activation-step-marker {
+    width: 27px;
+    height: 27px;
+    display: grid;
+    place-items: center;
+    border: 1px solid var(--line-strong);
+    border-radius: 50%;
+    color: var(--ink-soft);
+    background: var(--surface);
+    font-size: 13px;
+    font-weight: 600;
+  }
+  /* The app keeps every label at 400 and signals the current step through the
+     marker fill alone, so the row stays even rather than jumping as you advance. */
+  .activation-steps li strong { font-size: 11px; font-weight: 400; }
+  /* The marker fill is the only signal that the step changed, so it is worth
+     easing rather than cutting — it is also what the eye tracks when nobody
+     clicked. Matches the panel's 240ms so the two read as one movement. */
+  @media not (prefers-reduced-motion: reduce) {
+    .activation-steps li { transition: color 240ms ease; }
+    .activation-step-marker {
+      transition: background-color 240ms ease, border-color 240ms ease, color 240ms ease;
+    }
+  }
+  .activation-steps li.is-current { color: var(--ink); }
+  .activation-steps li.is-current .activation-step-marker {
+    border-color: var(--blue-deep);
+    background: var(--blue-deep);
+    color: var(--on-accent);
+  }
+  .activation-steps li.is-done .activation-step-marker {
+    border-color: var(--green);
+    color: var(--green);
+    background: var(--green-soft);
+  }
+  .activation-reset {
+    padding: 8px 2px;
+    border: 0;
+    color: var(--ink-soft);
+    background: transparent;
+    font: 600 12px/1.2 inherit;
+    cursor: pointer;
+  }
+  .activation-reset:hover { color: var(--ink); }
+  /* 42px gutters and a header/body split, matching the app's page-scaffold. */
+  .activation-main { min-width: 0; padding: 26px 42px 24px; display: flex; flex-direction: column; }
+  .activation-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: 24px; }
+  .activation-heading > div { display: grid; gap: 6px; }
+  .activation-heading h2 { margin: 0; font-size: 24px; line-height: 1.15; letter-spacing: -.01em; }
+  .activation-status { padding: 8px 10px; border: 1px solid var(--line); border-radius: 999px; background: var(--surface-muted); }
+  .activation-status > span { width: 7px; height: 7px; background: var(--ink-faint); box-shadow: none; }
+  .activation-status[data-kind="ready"] > span { background: var(--green); box-shadow: 0 0 0 4px var(--green-soft); }
+  .activation-status[data-kind="preview-gate"] > span,
+  .activation-status[data-kind="guide-only"] > span { background: var(--orange); box-shadow: 0 0 0 4px var(--orange-soft); }
+  .activation-status[data-kind="unsupported"] > span,
+  .activation-status[data-kind="error"] > span { background: var(--red); box-shadow: 0 0 0 4px var(--red-soft); }
+  .activation-subtitle { margin: 10px 0 0; max-width: 720px; color: var(--ink-soft); font-size: 13px; line-height: 1.5; }
+  .activation-panel {
+    min-height: 272px;
+    margin-top: 24px;
+    padding: 24px;
+    border: 1px solid var(--line);
+    border-radius: var(--radius-panel);
+    background: var(--paper-strong);
+    outline: none;
+  }
+  .activation-panel:focus-visible { box-shadow: 0 0 0 3px var(--blue-soft); }
+  /* Steps replace each other by toggling [hidden], which is a hard cut. Fading
+     the arriving panel up from slightly below and slightly small reads as one
+     step advancing rather than two panels swapping — and the scale is 0.985, not
+     a slide: this is a product window, not a carousel.
+
+     @starting-style is what makes the entry animate at all: the panel goes from
+     display:none straight to its final state, so without a declared starting
+     value there is nothing to transition from.
+
+     Transform only, deliberately — no fade. Text mid-opacity fails the contrast
+     audit for as long as the transition runs, and this page already holds itself
+     to keeping copy readable while the hero entrance plays. Movement carries the
+     step change without ever rendering the panel's own text at low contrast.
+
+     Only the entry is animated. Transitioning `display` on the way out would
+     keep the outgoing panel in flow for the whole 240ms, and since the panels
+     are siblings in normal flow the console would double in height every step. */
+  @media not (prefers-reduced-motion: reduce) {
+    .activation-panel:not([hidden]) {
+      transition: transform 240ms ease;
+      transform: none;
+    }
+  }
+  @starting-style {
+    @media not (prefers-reduced-motion: reduce) {
+      .activation-panel:not([hidden]) {
+        transform: translateY(8px) scale(0.985);
+      }
+    }
+  }
+  .activation-panel[data-panel="idle"], .activation-progress, .activation-result {
+    display: grid;
+    grid-template-columns: 92px minmax(0, 1fr);
+    align-items: center;
+    gap: 28px;
+  }
+  .activation-panel h3 { margin: 0; font-size: 22px; line-height: 1.18; }
+  .activation-panel p { margin: 9px 0 0; max-width: 640px; color: var(--ink-soft); font-size: 14px; line-height: 1.55; }
+  .activation-empty-mark { width: 84px; height: 84px; position: relative; display: grid; place-items: center; }
+  .activation-empty-mark::before, .activation-empty-mark::after, .activation-empty-mark span {
+    content: "";
+    position: absolute;
+    border-radius: 50%;
+    border: 1px solid var(--line-strong);
+  }
+  .activation-empty-mark::before { inset: 0; }
+  .activation-empty-mark::after { inset: 16px; border-color: var(--blue); }
+  .activation-empty-mark span:nth-child(1) { width: 8px; height: 8px; border: 0; background: var(--blue); }
+  .activation-empty-mark span:nth-child(2) { inset: 7px; border-style: dashed; }
+  .activation-empty-mark span:nth-child(3) { width: 42px; height: 1px; border: 0; border-radius: 0; background: var(--line-strong); transform: rotate(-35deg); }
+  .activation-scan { width: 84px; height: 84px; position: relative; border: 1px solid var(--line-strong); border-radius: 50%; }
+  .activation-scan::before, .activation-scan::after { content: ""; position: absolute; inset: 13px; border: 1px solid var(--line); border-radius: 50%; }
+  .activation-scan::after { inset: 29px; background: var(--blue); border: 0; box-shadow: 0 0 0 8px var(--blue-soft); }
+  .activation-scan span { position: absolute; inset: -1px; border-top: 2px solid var(--blue); border-right: 2px solid transparent; border-radius: 50%; animation: activation-spin 1s linear infinite; }
+  .activation-scan.is-verify::after { background: var(--green); box-shadow: 0 0 0 8px var(--green-soft); }
+  .activation-panel-copy { margin-bottom: 18px; }
+  .activation-choice-panel { padding: 20px; }
+  .activation-agent-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 10px; }
+  .activation-agent {
+    min-width: 0;
+    min-height: 74px;
+    padding: 11px 12px;
+    position: relative;
+    display: grid;
+    grid-template-columns: 30px minmax(0, 1fr) auto;
+    align-items: center;
+    gap: 10px;
+    text-align: left;
+    color: var(--ink);
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    background: var(--surface);
+    cursor: pointer;
+  }
+  .activation-agent:hover, .activation-agent[aria-pressed="true"] { border-color: var(--blue); background: var(--blue-soft); }
+  .activation-agent-copy { min-width: 0; display: grid; gap: 3px; }
+  .activation-agent-copy strong { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 13px; }
+  .activation-agent-copy small { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--ink-faint); font-size: 10px; }
+  .activation-agent-state { padding: 5px 7px; border-radius: 999px; color: var(--ink-soft); background: var(--surface-muted); font-size: 9px; font-weight: 700; white-space: nowrap; }
+  .activation-agent-state.is-ready { color: var(--green); background: var(--green-soft); }
+  .activation-agent-state.is-attention, .activation-agent-state.is-guide-only { color: var(--orange); background: var(--orange-soft); }
+  .activation-recommended { position: absolute; top: -7px; right: 9px; padding: 2px 6px; border-radius: 999px; color: var(--on-accent); background: var(--blue-deep); font-size: 8px; font-weight: 750; }
+  .activation-selection-line, .activation-verifying-pair, .activation-result-meta {
+    margin: 14px 0;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    color: var(--ink-soft);
+    font: 650 12px/1.3 ui-monospace, SFMono-Regular, Menlo, monospace;
+  }
+  .activation-selection-line span:first-child { color: var(--ink); }
+  .activation-provider-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 10px; }
+  .activation-provider {
+    min-height: 66px;
+    padding: 11px 13px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    color: var(--ink);
+    text-align: left;
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    background: var(--surface);
+    cursor: pointer;
+  }
+  .activation-provider > span:first-child { min-width: 0; display: grid; gap: 4px; }
+  .activation-provider strong { font-size: 13px; }
+  .activation-provider small { color: var(--ink-faint); font-size: 10px; }
+  .activation-provider:hover, .activation-provider[aria-pressed="true"] { border-color: var(--blue); background: var(--blue-soft); }
+  .activation-provider[data-compatibility="preview-gate"] small { color: var(--orange); }
+  .activation-provider[data-compatibility="unsupported"] small { color: var(--red); }
+  .activation-provider.is-recommended::after { content: "★"; color: var(--blue); font-size: 10px; }
+  .activation-provider-arrow { color: var(--ink-faint); }
+  .activation-mode-grid { display: grid; gap: 10px; }
+  .activation-mode {
+    padding: 13px 15px;
+    display: grid;
+    gap: 5px;
+    color: var(--ink);
+    text-align: left;
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    background: var(--surface);
+    cursor: pointer;
+  }
+  .activation-mode strong { font-size: 13px; }
+  .activation-mode small { color: var(--ink-faint); font-size: 11px; line-height: 1.45; }
+  .activation-mode:hover, .activation-mode[aria-pressed="true"] { border-color: var(--blue); background: var(--blue-soft); }
+
+  /* The custom endpoint is the one place the demo takes typed input, so it gets
+     a real label and a live verdict rather than a placeholder-only field. */
+  .activation-custom { margin-top: 12px; display: grid; gap: 6px; }
+  .activation-custom label { font-size: 11px; font-weight: 600; color: var(--ink-soft); }
+  .activation-custom input {
+    padding: 9px 11px;
+    color: var(--ink);
+    border: 1px solid var(--line-strong);
+    border-radius: 10px;
+    background: var(--surface);
+    font: 500 12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace;
+  }
+  .activation-custom input:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: 1px; }
+  .activation-custom-hint { font-size: 11px; color: var(--ink-faint); }
+  .activation-custom-hint[data-kind="ok"] { color: var(--green); }
+  .activation-custom-hint[data-kind="error"] { color: var(--red); }
+  .activation-register { display: grid; gap: 2px; font-size: 11px; color: var(--blue); }
+  .activation-register small { color: var(--ink-faint); }
+
+  .activation-model-grid { display: grid; gap: 8px; }
+  .activation-model {
+    padding: 10px 12px;
+    color: var(--ink);
+    text-align: left;
+    border: 1px solid var(--line);
+    border-radius: 10px;
+    background: var(--surface);
+    cursor: pointer;
+    font: 500 12px/1.3 ui-monospace, SFMono-Regular, Menlo, monospace;
+  }
+  .activation-model:hover, .activation-model[aria-pressed="true"] { border-color: var(--blue); background: var(--blue-soft); }
+  .activation-manual { margin-top: 12px; display: grid; gap: 6px; font-size: 11px; }
+  .activation-manual summary { color: var(--ink-soft); cursor: pointer; }
+  .activation-manual label { font-weight: 600; color: var(--ink-soft); }
+  .activation-manual input {
+    padding: 8px 11px;
+    color: var(--ink);
+    border: 1px solid var(--line-strong);
+    border-radius: 10px;
+    background: var(--surface);
+    font: 500 12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace;
+  }
+  .activation-manual input:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: 1px; }
+  .activation-steps li.is-skipped { opacity: 0.55; }
+  .activation-steps li.is-skipped strong::after { content: " ·"; }
+  .activation-verify { margin-top: 14px; }
+  .activation-verifying-pair strong, .activation-result-meta strong { color: var(--ink); }
+  .activation-result-icon {
+    width: 78px;
+    height: 78px;
+    display: grid;
+    place-items: center;
+    border-radius: 22px;
+    color: var(--green);
+    background: var(--green-soft);
+    font-size: 34px;
+    font-weight: 650;
+  }
+  .activation-result-icon svg { width: 36px; height: 36px; fill: none; stroke: currentColor; stroke-width: 2.4; stroke-linecap: round; stroke-linejoin: round; }
+  .activation-result-icon[data-kind="preview-gate"], .activation-result-icon[data-kind="guide-only"] { color: var(--orange); background: var(--orange-soft); }
+  .activation-result-icon[data-kind="unsupported"], .activation-result-icon[data-kind="error"] { color: var(--red); background: var(--red-soft); }
+  .activation-result-actions { margin-top: 18px; display: flex; flex-wrap: wrap; align-items: center; gap: 9px; }
+  .activation-log-wrap { min-height: 62px; margin-top: 16px; display: grid; grid-template-columns: 82px 1fr; gap: 12px; }
+  .activation-log-wrap > span { padding-top: 4px; color: var(--ink-faint); font: 700 9px/1.2 ui-monospace, SFMono-Regular, Menlo, monospace; letter-spacing: .1em; }
+  .activation-log { max-height: 58px; margin: 0; padding: 0; overflow: auto; list-style: none; color: var(--ink-soft); font: 11px/1.55 ui-monospace, SFMono-Regular, Menlo, monospace; }
+  .activation-log li::before { content: "> "; color: var(--blue); }
+  .activation-facts { min-height: 48px; padding: 10px 18px; display: grid; grid-template-columns: repeat(3, 1fr); gap: 18px; border-top: 1px solid var(--line); background: var(--paper-strong); }
+  .activation-facts span { display: flex; align-items: center; gap: 8px; color: var(--ink-soft); font-size: 11px; }
+  .activation-facts i {
+    width: 10px;
+    height: 6px;
+    display: inline-block;
+    border-left: 2px solid var(--green);
+    border-bottom: 2px solid var(--green);
+    transform: rotate(-45deg) translateY(-1px);
+  }
+
+  @media not (prefers-reduced-motion: reduce) {
+    .activation-agent, .activation-provider { transition: transform var(--dur-micro) var(--ease-apple), border-color var(--dur-micro) var(--ease-apple), background-color var(--dur-micro) var(--ease-apple); }
+    .activation-agent:hover, .activation-provider:hover { transform: translateY(-1px); }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .activation-scan span { animation: none; border: 2px solid var(--blue); }
+  }
+  @keyframes activation-spin { to { transform: rotate(360deg); } }
+
+  /* The sidebar is the first thing to go: it is workspace chrome, and the demo
+     never navigates. The stepper stays, since it is the actual progress. */
+  @media (max-width: 820px) {
+    .activation-body { grid-template-columns: 1fr; grid-template-rows: minmax(0, 1fr) auto; }
+    .activation-rail { display: none; }
+    .activation-footer { padding: 0 20px; }
+  }
+  @media (max-width: 680px) {
+    .activation-shell { width: min(100% - 28px, 1180px); }
+    .activation-topbar { padding: 10px 12px; }
+    .activation-kicker { display: none; }
+    .activation-body { min-height: 0; }
+    .activation-main { padding: 20px 14px 16px; }
+    .activation-heading h2 { font-size: 20px; }
+    .activation-subtitle { font-size: 12px; }
+    /* Labels drop out and the circles compress to a row of five markers. */
+    .activation-steps { margin-top: 16px; grid-auto-columns: minmax(0, 1fr); }
+    .activation-steps li strong { display: none; }
+    .activation-footer { min-height: 60px; padding: 0 14px; gap: 10px; }
+    .activation-footer-note { font-size: 11px; }
+    .activation-panel { min-height: 250px; margin-top: 18px; padding: 18px; }
+    .activation-panel[data-panel="idle"], .activation-progress, .activation-result { grid-template-columns: 1fr; gap: 16px; }
+    .activation-empty-mark, .activation-scan { width: 62px; height: 62px; }
+    .activation-panel h3 { font-size: 19px; }
+    .activation-agent-grid, .activation-provider-grid { grid-template-columns: 1fr; }
+    .activation-agent { min-height: 68px; }
+    .activation-facts { grid-template-columns: 1fr; gap: 8px; }
+    .activation-log-wrap { grid-template-columns: 1fr; gap: 4px; }
+  }
+</style>
diff --git a/site/src/components/AgentMark.astro b/site/src/components/AgentMark.astro
index f021765b..e59ab40f 100644
--- a/site/src/components/AgentMark.astro
+++ b/site/src/components/AgentMark.astro
@@ -15,9 +15,14 @@ const extensions: Record<string, string> = {
   "kilo-cli": "svg",
   aider: "png",
 };
+/* These two marks ship as fill="currentColor". Loaded through <img> the keyword
+   has no page to inherit from and falls back to black, which disappears on a
+   dark ground — so they get inverted there while the marks carrying their own
+   brand colours are left alone. */
+const monochrome = new Set(["codex", "opencode"]);
 const extension = extensions[id];
 const imageSource = extension ? `${import.meta.env.BASE_URL}images/agents/${id}.${extension}` : null;
 ---
 <span class="agent-mark-wrap" style={`--mark-size:${size}px`} aria-hidden="true">
-  {imageSource ? <img src={imageSource} alt="" width={size} height={size} loading="lazy" /> : <span class="agent-fallback">{name.slice(0, 1)}</span>}
+  {imageSource ? <img src={imageSource} alt="" width={size} height={size} loading="lazy" data-monochrome={monochrome.has(id) ? "" : undefined} /> : <span class="agent-fallback">{name.slice(0, 1)}</span>}
 </span>
diff --git a/site/src/components/CompatibilityExplorer.astro b/site/src/components/CompatibilityExplorer.astro
new file mode 100644
index 00000000..0a58a6ad
--- /dev/null
+++ b/site/src/components/CompatibilityExplorer.astro
@@ -0,0 +1,609 @@
+---
+import AgentMark from "./AgentMark.astro";
+import { catalog } from "../lib/catalog";
+import { localeFromPath, localePath } from "../i18n";
+import { useCatalogLabels } from "../i18n/catalog";
+import { protocolLabels } from "../lib/content";
+import { demoStateFor } from "../lib/demo-environment";
+import { compatibilityFor, type Compatibility } from "../lib/explorer";
+
+const locale = localeFromPath(Astro.url.pathname);
+const { agentDescriptions, groupLabels, agentFallbackDescription } = useCatalogLabels(locale);
+const technicalHref = (agentId: string) => localePath("zh-CN", `agents/${agentId}/`);
+const providerHref = (providerId: string) => localePath("zh-CN", `providers/${providerId}/`);
+const copy = locale === "en"
+  ? {
+      filters: "Explorer filters",
+      platform: "Platform",
+      setup: "Install path",
+      config: "Configuration",
+      protocol: "Protocol",
+      provider: "Provider",
+      demo: "Demo state",
+      all: "All",
+      managedInstall: "Managed install",
+      officialGuide: "Official guide",
+      managedConfig: "Managed config",
+      officialConfig: "Official config",
+      ready: "Ready",
+      attention: "Needs attention",
+      notInstalled: "Not installed",
+      clear: "Clear filters",
+      results: "agents shown",
+      noResults: "No agent matches this combination.",
+      noResultsBody: "Clear a filter or choose a provider that implements the selected protocol.",
+      sample: "Demo state",
+      locked: "Locked",
+      officialRelease: "Official release",
+      open: "Open details for",
+      close: "Close details",
+      overview: "Environment example",
+      installState: "Example install state",
+      configState: "Example config state",
+      lockedVersion: "Catalog version",
+      configPath: "Configuration path",
+      command: "Launch command",
+      backup: "Example backup",
+      backupYes: "Available",
+      backupNo: "None yet",
+      installed: "Installed",
+      configured: "Configured",
+      needsSetup: "Needs setup",
+      providerCompatibility: "Provider compatibility",
+      capability: "Activation boundary",
+      managedBoundary: "OneAgent can manage this agent's configuration and backs up an existing file before a managed write.",
+      guideBoundary: "This agent stays in its official install, sign-in or extension flow. OneAgent does not write private configuration for it.",
+      technical: "Technical reference (Chinese)",
+      source: "Upstream source",
+      providerReference: "Provider reference (Chinese)",
+      illustrative: "Illustrative machine state; catalog capabilities are real.",
+      compatibility: {
+        verified: "Verified",
+        supported: "Implementation supported",
+        "preview-gate": "Release candidate required",
+        unsupported: "Unsupported",
+      } as Record<Compatibility, string>,
+    }
+  : {
+      filters: "配置筛选",
+      platform: "平台",
+      setup: "安装路径",
+      config: "配置方式",
+      protocol: "协议",
+      provider: "Provider",
+      demo: "示例状态",
+      all: "全部",
+      managedInstall: "托管安装",
+      officialGuide: "官方引导",
+      managedConfig: "托管配置",
+      officialConfig: "官方配置",
+      ready: "Ready",
+      attention: "需处理",
+      notInstalled: "未安装",
+      clear: "清除筛选",
+      results: "个 Agent",
+      noResults: "没有 Agent 匹配这组条件。",
+      noResultsBody: "清除一个筛选，或选择实现了目标协议的 Provider。",
+      sample: "示例状态",
+      locked: "锁定",
+      officialRelease: "官方发行",
+      open: "打开详情：",
+      close: "关闭详情",
+      overview: "环境示例",
+      installState: "示例安装状态",
+      configState: "示例配置状态",
+      lockedVersion: "目录版本",
+      configPath: "配置位置",
+      command: "启动命令",
+      backup: "示例备份",
+      backupYes: "已有",
+      backupNo: "暂无",
+      installed: "已安装",
+      configured: "已配置",
+      needsSetup: "待配置",
+      providerCompatibility: "Provider 兼容性",
+      capability: "激活边界",
+      managedBoundary: "OneAgent 可以管理这个 Agent 的配置，并会在托管写入前备份已有文件。",
+      guideBoundary: "这个 Agent 保留官方安装、登录或扩展内流程；OneAgent 不写入它的私有配置。",
+      technical: "技术详情",
+      source: "上游源码",
+      providerReference: "Provider 详情",
+      illustrative: "机器状态属于示例；目录能力来自真实数据。",
+      compatibility: {
+        verified: "已验证",
+        supported: "实现支持",
+        "preview-gate": "需发布候选验证",
+        unsupported: "不支持",
+      } as Record<Compatibility, string>,
+    };
+
+const demoLabel = (status: string) => status === "ready"
+  ? copy.ready
+  : status === "attention"
+    ? copy.attention
+    : status === "guide-only"
+      ? copy.officialGuide
+      : copy.notInstalled;
+---
+<compatibility-explorer data-locale={locale}>
+  <section class="explorer-toolbar" aria-label={copy.filters}>
+    <label class="explorer-filter">
+      <span>{copy.platform}</span>
+      <select data-filter="platform">
+        <option value="">{copy.all}</option>
+        <option value="macos">macOS</option>
+        <option value="linux">Linux</option>
+        <option value="windows">Windows</option>
+      </select>
+    </label>
+    <label class="explorer-filter">
+      <span>{copy.setup}</span>
+      <select data-filter="setup">
+        <option value="">{copy.all}</option>
+        <option value="managed">{copy.managedInstall}</option>
+        <option value="guide">{copy.officialGuide}</option>
+      </select>
+    </label>
+    <label class="explorer-filter">
+      <span>{copy.config}</span>
+      <select data-filter="config">
+        <option value="">{copy.all}</option>
+        <option value="managed">{copy.managedConfig}</option>
+        <option value="official">{copy.officialConfig}</option>
+      </select>
+    </label>
+    <label class="explorer-filter">
+      <span>{copy.protocol}</span>
+      <select data-filter="protocol">
+        <option value="">{copy.all}</option>
+        <option value="openai">{protocolLabels.openai}</option>
+        <option value="anthropic">{protocolLabels.anthropic}</option>
+        <option value="responses">{protocolLabels.responses}</option>
+      </select>
+    </label>
+    <label class="explorer-filter">
+      <span>{copy.provider}</span>
+      <select data-filter="provider">
+        <option value="">{copy.all}</option>
+        {catalog.providers.map((provider) => <option value={provider.id}>{provider.name}</option>)}
+      </select>
+    </label>
+    <label class="explorer-filter">
+      <span>{copy.demo}</span>
+      <select data-filter="demo">
+        <option value="">{copy.all}</option>
+        <option value="ready">{copy.ready}</option>
+        <option value="attention">{copy.attention}</option>
+        <option value="guide-only">{copy.officialGuide}</option>
+        <option value="not-installed">{copy.notInstalled}</option>
+      </select>
+    </label>
+    <button class="button button-secondary explorer-clear" type="button" data-clear-filters>{copy.clear}</button>
+  </section>
+
+  <div class="explorer-result-line" aria-live="polite">
+    <strong data-result-count>{catalog.agents.length}</strong>
+    <span>{copy.results}</span>
+    <span aria-hidden="true">·</span>
+    <span>{copy.illustrative}</span>
+  </div>
+
+  <div class="explorer-grid" data-explorer-grid>
+    {catalog.agents.map((agent) => {
+      const demo = demoStateFor(agent);
+      const providers = catalog.providers
+        .filter((provider) => compatibilityFor(agent, provider) !== "unsupported")
+        .map((provider) => provider.id);
+      return (
+        <button
+          type="button"
+          class="explorer-card"
+          data-agent-card
+          data-agent-id={agent.id}
+          data-platforms={agent.platforms.join(" ")}
+          data-setup={agent.support.managedInstall ? "managed" : "guide"}
+          data-config={agent.support.managedConfig ? "managed" : "official"}
+          data-protocol={agent.protocol ?? ""}
+          data-providers={providers.join(" ")}
+          data-demo-status={demo.status}
+          aria-label={`${copy.open} ${agent.name}`}
+        >
+          <span class="explorer-card-head">
+            <AgentMark id={agent.id} name={agent.name} size={34} />
+            <span><strong>{agent.name}</strong><small>{groupLabels[agent.group] ?? agent.group}</small></span>
+            <span class:list={["explorer-demo-state", `is-${demo.status}`]}>{demoLabel(demo.status)}</span>
+          </span>
+          <span class="explorer-description">{agentDescriptions[agent.id] ?? agentFallbackDescription}</span>
+          <span class="explorer-chips">
+            <span class:list={["chip", agent.support.managedInstall && "chip-green"]}>{agent.support.managedInstall ? copy.managedInstall : copy.officialGuide}</span>
+            <span class:list={["chip", agent.support.managedConfig && "chip-blue"]}>{agent.support.managedConfig ? copy.managedConfig : copy.officialConfig}</span>
+            {agent.protocol && <span class="chip">{protocolLabels[agent.protocol]}</span>}
+          </span>
+          <span class="explorer-card-foot">
+            <span>{agent.lockedVersion ? `${copy.locked} ${agent.lockedVersion}` : copy.officialRelease}</span>
+            <span aria-hidden="true">↗</span>
+          </span>
+        </button>
+      );
+    })}
+  </div>
+
+  <div class="explorer-empty" data-explorer-empty hidden>
+    <strong>{copy.noResults}</strong>
+    <p>{copy.noResultsBody}</p>
+  </div>
+
+  <div hidden data-detail-templates>
+    {catalog.agents.map((agent) => {
+      const demo = demoStateFor(agent);
+      const version = demo.version === "locked"
+        ? agent.lockedVersion
+        : demo.version === "behind" && agent.lockedVersion
+          ? `< ${agent.lockedVersion}`
+          : agent.lockedVersion;
+      return (
+        <template data-agent-template={agent.id}>
+          <article class="drawer-content">
+            <header class="drawer-head">
+              <AgentMark id={agent.id} name={agent.name} size={44} />
+              <div>
+                <span class="activation-state-label">{copy.sample}</span>
+                <h2 id="explorer-drawer-title">{agent.name}</h2>
+                <p>{agentDescriptions[agent.id] ?? agentFallbackDescription}</p>
+              </div>
+              <span class:list={["explorer-demo-state", `is-${demo.status}`]}>{demoLabel(demo.status)}</span>
+            </header>
+
+            <section class="drawer-section">
+              <h3>{copy.overview}</h3>
+              <dl class="drawer-facts">
+                <div><dt>{copy.installState}</dt><dd>{demo.installed ? copy.installed : copy.notInstalled}</dd></div>
+                <div><dt>{copy.configState}</dt><dd>{demo.configured ? copy.configured : agent.support.officialInstallGuide ? copy.officialGuide : copy.needsSetup}</dd></div>
+                <div><dt>{copy.lockedVersion}</dt><dd>{version ?? copy.officialRelease}</dd></div>
+                <div><dt>{copy.backup}</dt><dd>{demo.hasBackup ? copy.backupYes : copy.backupNo}</dd></div>
+                <div><dt>{copy.configPath}</dt><dd><code>{agent.configPath ?? "—"}</code></dd></div>
+                <div><dt>{copy.command}</dt><dd><code>{agent.command ?? "—"}</code></dd></div>
+              </dl>
+            </section>
+
+            <section class="drawer-section">
+              <h3>{copy.providerCompatibility}</h3>
+              <div class="drawer-provider-list">
+                {catalog.providers.map((provider) => {
+                  const compatibility = compatibilityFor(agent, provider);
+                  return (
+                    <a href={providerHref(provider.id)} aria-label={`${provider.name} — ${copy.providerReference}`}>
+                      <span><strong>{provider.name}</strong><small>{agent.protocol ? protocolLabels[agent.protocol] : copy.officialGuide}{locale === "en" ? " · Chinese reference" : ""}</small></span>
+                      <span class:list={["drawer-compatibility", `is-${compatibility}`]}>{copy.compatibility[compatibility]}</span>
+                    </a>
+                  );
+                })}
+              </div>
+            </section>
+
+            <section class="drawer-section drawer-boundary">
+              <h3>{copy.capability}</h3>
+              <p>{agent.support.managedConfig ? copy.managedBoundary : copy.guideBoundary}</p>
+            </section>
+
+            <footer class="drawer-actions">
+              <a class="button button-primary" href={technicalHref(agent.id)}>{copy.technical}</a>
+              {agent.source && <a class="button button-secondary" href={agent.source} rel="noreferrer">{copy.source}</a>}
+            </footer>
+          </article>
+        </template>
+      );
+    })}
+  </div>
+
+  <dialog class="explorer-drawer" data-explorer-drawer aria-labelledby="explorer-drawer-title">
+    <div class="drawer-shell">
+      <button class="drawer-close" type="button" data-close-drawer aria-label={copy.close}>×</button>
+      <div data-drawer-slot></div>
+    </div>
+  </dialog>
+</compatibility-explorer>
+
+<script>
+  import { catalog } from "../lib/catalog";
+  import {
+    parseExplorerSearch,
+    serializeExplorerSearch,
+    type ExplorerSearchState,
+  } from "../lib/explorer";
+
+
+  class CompatibilityExplorerElement extends HTMLElement {
+    abort = new AbortController();
+    selectedAgent: string | null = null;
+    lastTrigger: HTMLElement | null = null;
+    suppressCloseUrl = false;
+
+    connectedCallback() {
+      if (this.dataset.initialized === "true") return;
+      this.dataset.initialized = "true";
+      const signal = this.abort.signal;
+      this.querySelectorAll<HTMLSelectElement>("[data-filter]").forEach((control) => {
+        control.addEventListener("change", () => this.filtersChanged(), { signal });
+      });
+      this.querySelector<HTMLButtonElement>("[data-clear-filters]")?.addEventListener("click", () => this.clearFilters(), { signal });
+      this.querySelectorAll<HTMLButtonElement>("[data-agent-card]").forEach((card) => {
+        card.addEventListener("click", () => this.openAgent(card.dataset.agentId || "", card), { signal });
+      });
+      this.querySelector<HTMLButtonElement>("[data-close-drawer]")?.addEventListener("click", () => this.drawer?.close(), { signal });
+      this.drawer?.addEventListener("close", () => this.drawerClosed(), { signal });
+      window.addEventListener("popstate", () => this.applyUrl(), { signal });
+      this.applyUrl();
+    }
+
+    disconnectedCallback() {
+      this.abort.abort();
+    }
+
+    get drawer() {
+      return this.querySelector<HTMLDialogElement>("[data-explorer-drawer]");
+    }
+
+    get locale() {
+      return this.dataset.locale === "en" ? "en" : "zh-CN";
+    }
+
+    control(name: string) {
+      return this.querySelector<HTMLSelectElement>(`[data-filter="${name}"]`);
+    }
+
+    applyUrl() {
+      const state = parseExplorerSearch(window.location.search, catalog);
+      this.setControl("platform", state.platform ?? "");
+      this.setControl("protocol", state.protocol ?? "");
+      this.setControl("provider", state.provider ?? "");
+      this.selectedAgent = state.agent;
+      this.filterCards();
+      if (state.agent) this.openAgent(state.agent, null, false);
+      else if (this.drawer?.open) {
+        this.suppressCloseUrl = true;
+        this.drawer.close();
+      }
+    }
+
+    setControl(name: string, value: string) {
+      const control = this.control(name);
+      if (control) control.value = value;
+    }
+
+    currentSearch(agent = this.selectedAgent): ExplorerSearchState {
+      return {
+        agent,
+        provider: this.control("provider")?.value || null,
+        platform: (this.control("platform")?.value || null) as ExplorerSearchState["platform"],
+        protocol: (this.control("protocol")?.value || null) as ExplorerSearchState["protocol"],
+      };
+    }
+
+    filtersChanged() {
+      const sanitized = parseExplorerSearch(`?${serializeExplorerSearch(this.currentSearch())}`, catalog);
+      this.selectedAgent = sanitized.agent;
+      this.setControl("platform", sanitized.platform ?? "");
+      this.setControl("protocol", sanitized.protocol ?? "");
+      this.setControl("provider", sanitized.provider ?? "");
+      this.writeUrl(sanitized);
+      this.filterCards();
+    }
+
+    clearFilters() {
+      this.querySelectorAll<HTMLSelectElement>("[data-filter]").forEach((control) => {
+        control.value = "";
+      });
+      this.selectedAgent = null;
+      if (this.drawer?.open) this.drawer.close();
+      this.writeUrl(this.currentSearch(null));
+      this.filterCards();
+      this.control("platform")?.focus();
+    }
+
+    filterCards() {
+      const platform = this.control("platform")?.value || "";
+      const setup = this.control("setup")?.value || "";
+      const config = this.control("config")?.value || "";
+      const protocol = this.control("protocol")?.value || "";
+      const provider = this.control("provider")?.value || "";
+      const demo = this.control("demo")?.value || "";
+      let visible = 0;
+
+      this.querySelectorAll<HTMLButtonElement>("[data-agent-card]").forEach((card) => {
+        const matches = (!platform || (card.dataset.platforms || "").split(" ").includes(platform))
+          && (!setup || card.dataset.setup === setup)
+          && (!config || card.dataset.config === config)
+          && (!protocol || card.dataset.protocol === protocol)
+          && (!provider || (card.dataset.providers || "").split(" ").includes(provider))
+          && (!demo || card.dataset.demoStatus === demo);
+        card.hidden = !matches;
+        card.classList.toggle("is-selected", card.dataset.agentId === this.selectedAgent);
+        if (matches) visible += 1;
+      });
+
+      const count = this.querySelector<HTMLElement>("[data-result-count]");
+      if (count) count.textContent = String(visible);
+      const empty = this.querySelector<HTMLElement>("[data-explorer-empty]");
+      if (empty) empty.hidden = visible !== 0;
+    }
+
+    openAgent(agentId: string, trigger: HTMLElement | null, updateUrl = true) {
+      const agent = catalog.agents.find((candidate) => candidate.id === agentId);
+      const template = this.querySelector<HTMLTemplateElement>(`template[data-agent-template="${agentId}"]`);
+      const slot = this.querySelector<HTMLElement>("[data-drawer-slot]");
+      if (!agent || !template || !slot || !this.drawer) return;
+
+      const sanitized = parseExplorerSearch(`?${serializeExplorerSearch(this.currentSearch(agentId))}`, catalog);
+      this.selectedAgent = agentId;
+      this.setControl("platform", sanitized.platform ?? "");
+      this.setControl("protocol", sanitized.protocol ?? "");
+      this.setControl("provider", sanitized.provider ?? "");
+      slot.replaceChildren(template.content.cloneNode(true));
+      this.lastTrigger = trigger;
+      this.filterCards();
+      if (!this.drawer.open) this.drawer.showModal();
+      this.querySelector<HTMLButtonElement>("[data-close-drawer]")?.focus();
+      if (updateUrl) this.writeUrl({ ...sanitized, agent: agentId });
+    }
+
+    drawerClosed() {
+      if (this.suppressCloseUrl) {
+        this.suppressCloseUrl = false;
+        return;
+      }
+      this.selectedAgent = null;
+      this.filterCards();
+      this.writeUrl(this.currentSearch(null));
+      this.lastTrigger?.focus();
+      this.lastTrigger = null;
+    }
+
+    writeUrl(state: ExplorerSearchState) {
+      const query = serializeExplorerSearch(state);
+      const next = `${window.location.pathname}${query ? `?${query}` : ""}`;
+      window.history.replaceState({}, "", next);
+    }
+  }
+
+  if (!customElements.get("compatibility-explorer")) {
+    customElements.define("compatibility-explorer", CompatibilityExplorerElement);
+  }
+</script>
+
+<style>
+  compatibility-explorer { display: block; }
+  .explorer-toolbar {
+    padding: 18px;
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr)) auto;
+    gap: 12px;
+    align-items: end;
+    border: 1px solid var(--line);
+    border-radius: var(--radius-panel);
+    background: var(--surface);
+    box-shadow: var(--shadow-lift);
+  }
+  .explorer-filter { min-width: 0; display: grid; gap: 7px; }
+  .explorer-filter > span { color: var(--ink-faint); font-size: 11px; font-weight: 700; letter-spacing: .06em; text-transform: uppercase; }
+  .explorer-filter select {
+    width: 100%;
+    min-height: 42px;
+    padding: 0 34px 0 11px;
+    color: var(--ink);
+    border: 1px solid var(--line-strong);
+    border-radius: var(--radius-control);
+    background: var(--paper-strong);
+    font: 600 13px/1 system-ui, sans-serif;
+  }
+  .explorer-clear { grid-column: 4; grid-row: 1 / span 2; align-self: stretch; }
+  .explorer-result-line { margin: 24px 0 14px; display: flex; flex-wrap: wrap; align-items: center; gap: 7px; color: var(--ink-faint); font-size: 13px; }
+  .explorer-result-line strong { color: var(--ink); font-size: 16px; }
+  .explorer-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 14px; }
+  .explorer-card {
+    min-width: 0;
+    min-height: 254px;
+    padding: 18px;
+    display: flex;
+    flex-direction: column;
+    text-align: left;
+    color: var(--ink);
+    border: 1px solid var(--line);
+    border-radius: var(--radius-panel);
+    background: var(--surface);
+    cursor: pointer;
+  }
+  .explorer-card:hover, .explorer-card.is-selected { border-color: var(--blue); box-shadow: var(--shadow-lift); }
+  .explorer-card-head { display: grid; grid-template-columns: 38px minmax(0, 1fr) auto; align-items: center; gap: 11px; }
+  .explorer-card-head > span:nth-child(2) { min-width: 0; display: grid; gap: 3px; }
+  .explorer-card-head strong { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 16px; }
+  .explorer-card-head small { color: var(--ink-faint); font-size: 11px; }
+  .explorer-demo-state { padding: 5px 7px; border-radius: 999px; color: var(--ink-soft); background: var(--surface-muted); font-size: 9px; font-weight: 750; white-space: nowrap; }
+  .explorer-demo-state.is-ready { color: var(--green); background: var(--green-soft); }
+  .explorer-demo-state.is-attention, .explorer-demo-state.is-guide-only { color: var(--orange); background: var(--orange-soft); }
+  .explorer-description { margin-top: 18px; color: var(--ink-soft); font-size: 13px; line-height: 1.5; }
+  .explorer-chips { margin-top: 16px; display: flex; flex-wrap: wrap; gap: 6px; }
+  .explorer-card-foot { margin-top: auto; padding-top: 18px; display: flex; justify-content: space-between; gap: 12px; color: var(--ink-faint); font: 600 11px/1.3 ui-monospace, SFMono-Regular, Menlo, monospace; }
+  .explorer-empty { padding: 64px 24px; text-align: center; border: 1px dashed var(--line-strong); border-radius: var(--radius-panel); }
+  .explorer-empty strong { font-size: 20px; }
+  .explorer-empty p { margin: 8px 0 0; color: var(--ink-soft); }
+  .explorer-drawer {
+    width: min(580px, 100%);
+    height: 100%;
+    max-width: none;
+    max-height: none;
+    margin: 0 0 0 auto;
+    padding: 0;
+    overflow: hidden;
+    color: var(--ink);
+    border: 0;
+    border-left: 1px solid var(--line-strong);
+    background: var(--surface);
+    box-shadow: -24px 0 70px rgba(0, 0, 0, .22);
+  }
+  .explorer-drawer::backdrop { background: rgba(8, 13, 17, .52); backdrop-filter: blur(3px); }
+  .drawer-shell { height: 100%; position: relative; overflow: auto; }
+  .drawer-close {
+    width: 38px;
+    height: 38px;
+    position: sticky;
+    top: 14px;
+    float: right;
+    margin: 14px 16px -52px 0;
+    z-index: 2;
+    border: 1px solid var(--line);
+    border-radius: 50%;
+    color: var(--ink);
+    background: color-mix(in srgb, var(--surface) 88%, transparent);
+    backdrop-filter: blur(12px);
+    font-size: 24px;
+    cursor: pointer;
+  }
+  .drawer-content { padding: 54px 34px 36px; }
+  .drawer-head { display: grid; grid-template-columns: 48px minmax(0, 1fr) auto; align-items: start; gap: 14px; }
+  .drawer-head h2 { margin: 5px 0 0; font-size: 30px; line-height: 1.1; }
+  .drawer-head p { margin: 10px 0 0; color: var(--ink-soft); font-size: 14px; line-height: 1.5; }
+  .drawer-section { margin-top: 34px; padding-top: 24px; border-top: 1px solid var(--line); }
+  .drawer-section h3 { margin: 0 0 15px; font-size: 17px; }
+  .drawer-facts { margin: 0; display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 1px; border: 1px solid var(--line); background: var(--line); }
+  .drawer-facts div { min-width: 0; padding: 13px; background: var(--paper-strong); }
+  .drawer-facts dt { color: var(--ink-faint); font-size: 10px; font-weight: 700; letter-spacing: .05em; text-transform: uppercase; }
+  .drawer-facts dd { margin: 6px 0 0; overflow-wrap: anywhere; font-size: 13px; }
+  .drawer-facts code { font-size: 11px; }
+  .drawer-provider-list { display: grid; border-top: 1px solid var(--line); }
+  .drawer-provider-list a { padding: 13px 2px; display: flex; align-items: center; justify-content: space-between; gap: 16px; border-bottom: 1px solid var(--line); }
+  .drawer-provider-list a > span:first-child { display: grid; gap: 3px; }
+  .drawer-provider-list strong { font-size: 13px; }
+  .drawer-provider-list small { color: var(--ink-faint); font-size: 10px; }
+  .drawer-compatibility { font-size: 10px; font-weight: 750; }
+  .drawer-compatibility.is-verified, .drawer-compatibility.is-supported { color: var(--green); }
+  .drawer-compatibility.is-preview-gate { color: var(--orange); }
+  .drawer-compatibility.is-unsupported { color: var(--red); }
+  .drawer-boundary { padding: 18px; border: 1px solid var(--line); border-radius: var(--radius-panel); background: var(--paper-strong); }
+  .drawer-boundary p { margin: 0; color: var(--ink-soft); font-size: 13px; line-height: 1.55; }
+  .drawer-actions { margin-top: 28px; display: flex; flex-wrap: wrap; gap: 9px; }
+
+  @media not (prefers-reduced-motion: reduce) {
+    .explorer-card { transition: transform var(--dur-micro) var(--ease-apple), border-color var(--dur-micro) var(--ease-apple), box-shadow var(--dur-micro) var(--ease-apple); }
+    .explorer-card:hover { transform: translateY(-2px); }
+    .explorer-drawer[open] { animation: drawer-in 260ms var(--ease-enter) both; }
+  }
+  @keyframes drawer-in { from { transform: translateX(28px); } }
+
+  @media (max-width: 980px) {
+    .explorer-toolbar { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+    .explorer-clear { grid-column: auto; grid-row: auto; }
+    .explorer-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  }
+  @media (max-width: 680px) {
+    .explorer-toolbar { grid-template-columns: 1fr 1fr; padding: 14px; }
+    .explorer-clear { grid-column: 1 / -1; }
+    .explorer-grid { grid-template-columns: 1fr; }
+    .explorer-card { min-height: 228px; }
+    .explorer-drawer { width: 100%; border-left: 0; }
+    .drawer-content { padding: 56px 18px 28px; }
+    .drawer-head { grid-template-columns: 48px minmax(0, 1fr); }
+    .drawer-head > .explorer-demo-state { grid-column: 2; justify-self: start; }
+    .drawer-facts { grid-template-columns: 1fr; }
+  }
+</style>
diff --git a/site/src/components/DownloadSelector.astro b/site/src/components/DownloadSelector.astro
index 486966ed..52935bfe 100644
--- a/site/src/components/DownloadSelector.astro
+++ b/site/src/components/DownloadSelector.astro
@@ -1,27 +1,129 @@
 ---
-import releaseIndexData from "../generated/release-index.json";
-import { binaryArtifact, formatBytes, formatDate, primaryDownload, type ReleaseChannel } from "../lib/downloads";
+import { bestLocaleFor, localeFromPath, localePath } from "../i18n";
+import { formatBytes, formatDate } from "../lib/downloads";
+import { binaryArtifact, getPreviewChannel, primaryDownload } from "../lib/release-channel";
 
-const releaseIndex = releaseIndexData as unknown as { channels: ReleaseChannel[] };
-const channel = releaseIndex.channels.find((item) => item.channel === "technical-preview-unsigned")!;
-const defaultTarget = channel.targets.find((target) => target.status === "available") ?? channel.targets[0];
+/* Everything below reads off a channel: the platform picker, the checksum, the
+   size. With no release published there is nothing to pick between, so the
+   component renders a single "not published yet" notice instead of four empty
+   panels that look like a broken page. */
+const channel = await getPreviewChannel();
+const defaultTarget = channel?.targets.find((target) => target.status === "available") ?? channel?.targets[0] ?? null;
+const locale = localeFromPath(Astro.url.pathname);
+const href = (path: string) => localePath(bestLocaleFor(locale, path), path);
+const c = locale === "en"
+  ? {
+      legend: "Choose platform and architecture",
+      available: "Available",
+      pending: "Verifying",
+      detected: "Showing the platform that is currently downloadable; you can switch at any time.",
+      notStableTitle: "This is not stable",
+      notStableBody: "The current package is unsigned and unnotarised. OneAgent does not document ways around your operating system's security policy.",
+      verified: "Verified and downloadable",
+      version: "Version",
+      channelLabel: "Release channel",
+      size: "File size",
+      built: "Build date",
+      signing: "Signing status",
+      unsigned: "Unsigned, unnotarised",
+      verification: "Verification",
+      verificationValue: "Native build + cleanroom passed",
+      download: (platform: string) => `Download the ${platform} preview`,
+      quickstart: "Read the quickstart",
+      sameBuildTitle: "You get the verified official build",
+      sameBuildBody: "This site, GitHub Releases and any mirror must serve the identical SHA-256. Repackaging is not permitted.",
+      checksumTitle: "macOS verification command",
+      copy: "Copy",
+      copied: "Copied",
+      cleanroomNote: "The cleanroom evidence applies to this file's exact SHA-256; any change to the package requires re-verification.",
+      unavailableTitle: "This platform has no public release yet",
+      unavailableBody: "The build workflow is in place, but until the native build, cleanroom evidence and release metadata are all present there is no empty download button and no CI artifact described as generally available.",
+      progress: "See release progress",
+      channelValue: "Unsigned technical preview",
+      fallbackPlatform: "current platform",
+      detectExact: "Detected as {full}. You can still switch manually.",
+      detectArchOnly: "Detected as {name} {arch}, but there is no exact build for that architecture here — do not run a build for a mismatched architecture.",
+      detectPlatformOnly: "Detected as {name}, but the browser cannot reliably tell the chip architecture. Confirm the option before downloading.",
+    }
+  : {
+      legend: "选择平台与架构",
+      available: "可下载",
+      pending: "验证中",
+      detected: "已优先显示当前可下载的平台；你可以随时手动切换。",
+      notStableTitle: "这不是 Stable",
+      notStableBody: "当前包未签名、未公证。OneAgent 不提供绕过操作系统安全策略的说明。",
+      verified: "已验证可下载",
+      version: "版本",
+      channelLabel: "发行渠道",
+      size: "文件大小",
+      built: "构建日期",
+      signing: "签名状态",
+      unsigned: "未签名、未公证",
+      verification: "验证状态",
+      verificationValue: "原生构建 + cleanroom 通过",
+      download: (platform: string) => `下载 ${platform} 预览版`,
+      quickstart: "查看快速开始",
+      sameBuildTitle: "下载即得到被校验的官方同包产物",
+      sameBuildBody: "任何官网、GitHub Release 或镜像渠道都必须保持相同 SHA-256，禁止二次打包。",
+      checksumTitle: "macOS 校验命令",
+      copy: "复制",
+      copied: "已复制",
+      cleanroomNote: "cleanroom 证据只对应此文件的精确 SHA-256；包体变化后必须重新验证。",
+      unavailableTitle: "这个平台尚未公开发行",
+      unavailableBody: "构建工作流已经保留，但在原生构建、cleanroom 证据和发行元数据齐备前，不提供空下载按钮，也不把 CI 产物描述为正式可用。",
+      progress: "查看发行进度",
+      channelValue: "未签名技术预览版",
+      fallbackPlatform: "当前平台",
+      detectExact: "已识别为 {full}；你仍可手动切换。",
+      detectArchOnly: "已识别为 {name} {arch}，当前目录没有完全匹配的构建；请勿运行架构不匹配的包。",
+      detectPlatformOnly: "已识别为 {name}，但浏览器无法可靠判断芯片架构；请确认选项后下载。",
+    };
 ---
+{!channel || !defaultTarget ? (
+  <div class="notice notice-warning">
+    <span class="notice-mark">!</span>
+    <div>
+      <strong>{c.unavailableTitle}</strong>
+      <p>{c.unavailableBody}</p>
+    </div>
+  </div>
+) : (
 <div class="download-layout" data-download-selector>
   <aside class="platform-control">
-    <label for="platform-target">选择平台与架构</label>
-    <select id="platform-target" data-platform-select>
+    <fieldset class="platform-picker" data-platform-picker>
+      <legend>{c.legend}</legend>
       {channel.targets.map((target) => (
-        <option value={target.id} selected={target.id === defaultTarget.id}>
-          {target.platformLabel} · {target.archLabel}
-        </option>
+        <label class="platform-option">
+          <input
+            type="radio"
+            name="platform-target"
+            value={target.id}
+            checked={target.id === defaultTarget.id}
+            data-platform-radio
+          />
+          <span class="platform-option-body">
+            <span class="platform-option-name">{target.platformLabel}</span>
+            <span class="platform-option-arch">{target.archLabel}</span>
+          </span>
+          {target.status === "available"
+            ? <span class="chip chip-green">{c.available}</span>
+            : <span class="chip chip-orange">{c.pending}</span>}
+        </label>
       ))}
-    </select>
-    <p class="detected-note" data-detected-note>已优先显示当前可下载的平台；你可以随时手动切换。</p>
+    </fieldset>
+    <p
+      class="detected-note"
+      data-detected-note
+      data-detect-exact={c.detectExact}
+      data-detect-arch={c.detectArchOnly}
+      data-detect-platform={c.detectPlatformOnly}
+      data-fallback={c.fallbackPlatform}
+    >{c.detected}</p>
     <div class="notice notice-warning" style="margin-top:22px">
       <span class="notice-mark">!</span>
       <div>
-        <strong>这不是 Stable</strong>
-        <p>当前包未签名、未公证。OneAgent 不提供绕过操作系统安全策略的说明。</p>
+        <strong>{c.notStableTitle}</strong>
+        <p>{c.notStableBody}</p>
       </div>
     </div>
   </aside>
@@ -37,48 +139,51 @@ const defaultTarget = channel.targets.find((target) => target.status === "availa
               <h2>{target.platformLabel}</h2>
               <p>{target.archLabel}</p>
             </div>
-            {target.status === "available" ? <span class="chip chip-green">已验证可下载</span> : <span class="chip chip-orange">验证中</span>}
+            {target.status === "available" ? <span class="chip chip-green">{c.verified}</span> : <span class="chip chip-orange">{c.pending}</span>}
           </div>
 
           {target.status === "available" && artifact && download ? (
             <>
               <dl class="release-meta-grid">
-                <div><dt>版本</dt><dd>{channel.version}</dd></div>
-                <div><dt>发行渠道</dt><dd>{channel.label}</dd></div>
-                <div><dt>文件大小</dt><dd>{formatBytes(artifact.bytes)}</dd></div>
-                <div><dt>构建日期</dt><dd>{formatDate(target.built_at)}</dd></div>
-                <div><dt>签名状态</dt><dd>未签名、未公证</dd></div>
-                <div><dt>验证状态</dt><dd>原生构建 + cleanroom 通过</dd></div>
+                <div><dt>{c.version}</dt><dd>{channel.version}</dd></div>
+                <div><dt>{c.channelLabel}</dt><dd>{c.channelValue}</dd></div>
+                <div><dt>{c.size}</dt><dd>{formatBytes(artifact.bytes)}</dd></div>
+                <div><dt>{c.built}</dt><dd>{formatDate(target.built_at)}</dd></div>
+                <div><dt>{c.signing}</dt><dd>{c.unsigned}</dd></div>
+                <div><dt>{c.verification}</dt><dd>{c.verificationValue}</dd></div>
               </dl>
               <div class="download-action">
-                <a class="button button-primary" href={download.url} download>下载 {target.platformLabel} 预览版</a>
-                <a class="button button-secondary" href="quickstart/">查看快速开始</a>
+                <a class="button button-primary" href={download.url} download>{c.download(target.platformLabel)}</a>
+                <a class="button button-secondary" href={href("quickstart/")}>{c.quickstart}</a>
               </div>
               <div class="notice notice-info">
                 <span class="notice-mark">i</span>
                 <div>
-                  <strong>下载即得到被校验的官方同包产物</strong>
-                  <p>任何官网、GitHub Release 或镜像渠道都必须保持相同 SHA-256，禁止二次打包。</p>
+                  <strong>{c.sameBuildTitle}</strong>
+                  <p>{c.sameBuildBody}</p>
                 </div>
               </div>
               <div class="hash-block">
                 <p><strong>SHA-256</strong></p>
                 <div class="hash-row">
-                  <code class="hash-value">{artifact.sha256}</code>
-                  <button class="copy-button" type="button" data-copy={artifact.sha256}>复制</button>
+                  {/* Both this and the command below scroll horizontally on narrow
+                      screens, so they need to be reachable without a pointer
+                      (WCAG 2.1.1). The label names which value has focus. */}
+                  <code class="hash-value" tabindex="0" role="group" aria-label="SHA-256">{artifact.sha256}</code>
+                  <button class="copy-button" type="button" data-copy={artifact.sha256} data-copy-label={c.copy} data-copied-label={c.copied}>{c.copy}</button>
                 </div>
               </div>
               <div class="hash-block">
-                <p><strong>macOS 校验命令</strong></p>
-                <pre class="code-block"><code>shasum -a 256 {artifact.file}</code></pre>
+                <p><strong>{c.checksumTitle}</strong></p>
+                <pre class="code-block" tabindex="0" role="group" aria-label={c.checksumTitle}><code>shasum -a 256 {artifact.file}</code></pre>
               </div>
-              <p class="hero-note">cleanroom 证据只对应此文件的精确 SHA-256；包体变化后必须重新验证。</p>
+              <p class="hero-note">{c.cleanroomNote}</p>
             </>
           ) : (
             <div class="unavailable-panel">
-              <h3>这个平台尚未公开发行</h3>
-              <p>构建工作流已经保留，但在原生构建、cleanroom 证据和发行元数据齐备前，不提供空下载按钮，也不把 CI 产物描述为正式可用。</p>
-              <a class="button button-secondary" href="changelog/">查看发行进度</a>
+              <h3>{c.unavailableTitle}</h3>
+              <p>{c.unavailableBody}</p>
+              <a class="button button-secondary" href={href("changelog/")}>{c.progress}</a>
             </div>
           )}
         </section>
@@ -86,12 +191,13 @@ const defaultTarget = channel.targets.find((target) => target.status === "availa
     })}
   </div>
 </div>
+)}
 
 <script>
   import { detectTargetFromUserAgent } from "../lib/downloads";
 
   const root = document.querySelector<HTMLElement>("[data-download-selector]");
-  const select = root?.querySelector<HTMLSelectElement>("[data-platform-select]");
+  const radios = root ? Array.from(root.querySelectorAll<HTMLInputElement>("[data-platform-radio]")) : [];
   const note = root?.querySelector<HTMLElement>("[data-detected-note]");
   const panels = root ? Array.from(root.querySelectorAll<HTMLElement>("[data-release-panel]")) : [];
 
@@ -103,37 +209,61 @@ const defaultTarget = channel.targets.find((target) => target.status === "availa
     });
   };
 
-  if (select) {
+  // The detection notes are localised templates passed from the server through
+  // data attributes, so an English reader never sees the Chinese fallback that a
+  // hardcoded string would leave behind. {full}/{name}/{arch} are filled client-
+  // side because the platform name only exists in the rendered DOM.
+  const tplExact = note?.dataset.detectExact ?? "";
+  const tplArch = note?.dataset.detectArch ?? "";
+  const tplPlatform = note?.dataset.detectPlatform ?? "";
+  const fallbackPlatform = note?.dataset.fallback ?? "";
+  const fill = (template: string, vars: Record<string, string>) =>
+    template.replace(/\{(\w+)\}/g, (_, key: string) => vars[key] ?? "");
+
+  const labelFor = (radio: HTMLInputElement) => {
+    const name = radio.parentElement?.querySelector(".platform-option-name")?.textContent?.trim() ?? fallbackPlatform;
+    const arch = radio.parentElement?.querySelector(".platform-option-arch")?.textContent?.trim() ?? "";
+    return { name, full: arch ? `${name} · ${arch}` : name };
+  };
+
+  if (radios.length) {
     const detected = detectTargetFromUserAgent(navigator.userAgent);
     if (detected) {
-      const exact = Array.from(select.options).find((option) => option.value === `${detected.platform}-${detected.arch}`);
-      const samePlatform = Array.from(select.options).find((option) => option.value.startsWith(`${detected.platform}-`));
-      const option = exact ?? samePlatform;
-      if (option) {
-        select.value = option.value;
-        show(option.value);
+      const exact = radios.find((radio) => radio.value === `${detected.platform}-${detected.arch}`);
+      const samePlatform = radios.find((radio) => radio.value.startsWith(`${detected.platform}-`));
+      const match = exact ?? samePlatform;
+      if (match) {
+        match.checked = true;
+        show(match.value);
         if (note) {
-          const selectedLabel = option.textContent?.trim() ?? "当前平台";
-          const platformLabel = selectedLabel.split("·", 1)[0]?.trim() ?? selectedLabel;
-          if (exact) note.textContent = `已识别为 ${selectedLabel}；你仍可手动切换。`;
+          const { name, full } = labelFor(match);
+          if (exact) note.textContent = fill(tplExact, { full, name });
           else if (detected.arch) {
             const architecture = detected.arch === "arm64" ? "ARM64" : "x64";
-            note.textContent = `已识别为 ${platformLabel} ${architecture}，当前目录没有完全匹配的构建；请勿运行架构不匹配的包。`;
+            note.textContent = fill(tplArch, { name, arch: architecture });
           } else {
-            note.textContent = `已识别为 ${platformLabel}，但浏览器无法可靠判断芯片架构；请确认选项后下载。`;
+            note.textContent = fill(tplPlatform, { name });
           }
         }
       }
     }
-    select.addEventListener("change", () => show(select.value));
+    // Radio groups fire change on the newly selected input, and arrow-key
+    // navigation moves selection too, so one listener per input covers both
+    // pointer and keyboard without any roving-tabindex bookkeeping.
+    radios.forEach((radio) => {
+      radio.addEventListener("change", () => {
+        if (radio.checked) show(radio.value);
+      });
+    });
   }
 
   root?.querySelectorAll<HTMLButtonElement>("[data-copy]").forEach((button) => {
     button.addEventListener("click", async () => {
       const value = button.dataset.copy ?? "";
       await navigator.clipboard.writeText(value);
-      button.textContent = "已复制";
-      window.setTimeout(() => { button.textContent = "复制"; }, 1500);
+      const idle = button.dataset.copyLabel ?? button.textContent ?? "";
+      button.textContent = button.dataset.copiedLabel ?? idle;
+      window.setTimeout(() => { button.textContent = idle; }, 1500);
     });
   });
 </script>
diff --git a/site/src/components/Footer.astro b/site/src/components/Footer.astro
index 736c39a2..f29178b4 100644
--- a/site/src/components/Footer.astro
+++ b/site/src/components/Footer.astro
@@ -1,38 +1,69 @@
 ---
 import BrandMark from "./BrandMark.astro";
+import { bestLocaleFor, localeFromPath, localePath, switchesLanguage } from "../i18n";
+import { useTranslations } from "../i18n/ui";
+import { releasesPageUrl } from "../lib/downloads";
+
 const year = new Date().getUTCFullYear();
+const locale = localeFromPath(Astro.url.pathname);
+const t = useTranslations(locale);
+const href = (path: string) => localePath(bestLocaleFor(locale, path), path);
+/* Column links, grouped as rendered. A `path` is resolved per locale and gets a
+   hint when the target has no translation; an `href` is an absolute artifact URL
+   that is the same in every locale. */
+type FooterLink = { path: string; label: string } | { href: string; label: string };
+const columns: { heading: string; links: FooterLink[] }[] = [
+  {
+    heading: t("footer.start"),
+    links: [
+      { path: "downloads/", label: t("footer.downloadCenter") },
+      { path: "quickstart/", label: t("nav.quickstart") },
+      { path: "changelog/", label: t("nav.changelog") },
+    ],
+  },
+  {
+    heading: t("footer.capability"),
+    links: [
+      { path: "explore/", label: t("nav.explorer") },
+      { path: "agents/", label: t("footer.agentCatalog") },
+      { path: "providers/", label: t("footer.providerCatalog") },
+    ],
+  },
+  {
+    heading: t("footer.trust"),
+    links: [
+      { path: "support/", label: t("footer.supportFeedback") },
+      // A published artifact rather than a page: same URL in every locale, so it
+      // is exempt from the locale resolution and the hint.
+      { href: releasesPageUrl, label: t("footer.releaseIndex") },
+    ],
+  },
+];
 ---
 <footer class="site-footer">
   <div class="shell footer-grid">
     <div class="footer-brand">
-      <a class="wordmark" href="">
+      <a class="wordmark" href={href("")}>
         <span class="wordmark-mark"><BrandMark size={22} /></span>
         <span>OneAgent</span>
       </a>
-      <p>可信的本地 AI 开发环境激活器。</p>
-      <p class="footer-fine">不提供共享 Key，不代理模型请求，不重新分发第三方 Agent。</p>
-    </div>
-    <div>
-      <strong>开始</strong>
-      <a href="downloads/">下载中心</a>
-      <a href="quickstart/">快速开始</a>
-      <a href="changelog/">更新日志</a>
-    </div>
-    <div>
-      <strong>能力</strong>
-      <a href="agents/">Agent 兼容目录</a>
-      <a href="providers/">Provider 目录</a>
-      <a href="enterprise/">企业服务</a>
-    </div>
-    <div>
-      <strong>信任</strong>
-      <a href="security/">安全与隐私</a>
-      <a href="support/">支持与反馈</a>
-      <a href="release-index.json">发行索引 JSON</a>
+      <p>{t("footer.tagline")}</p>
+      <p class="footer-fine">{t("footer.boundary")}</p>
     </div>
+    {columns.map((column) => (
+      <div>
+        <strong>{column.heading}</strong>
+        {column.links.map((link) => (
+          <a href={"path" in link ? href(link.path) : link.href}>
+            {link.label}
+            {"path" in link && switchesLanguage(locale, link.path) && <span class="lang-hint">{t("nav.chineseOnly")}</span>}
+          </a>
+        ))}
+      </div>
+    ))}
   </div>
   <div class="shell footer-bottom">
     <span>© {year} OneAgent</span>
-    <span>当前公开渠道：technical-preview-unsigned</span>
+    <span>{t("footer.channel")}</span>
   </div>
 </footer>
diff --git a/site/src/components/Header.astro b/site/src/components/Header.astro
index 1d5a5f31..3d5b162c 100644
--- a/site/src/components/Header.astro
+++ b/site/src/components/Header.astro
@@ -1,38 +1,56 @@
 ---
 import BrandMark from "./BrandMark.astro";
+import ThemeToggle from "./ThemeToggle.astro";
+import LocaleSwitch from "./LocaleSwitch.astro";
+import { bestLocaleFor, localeFromPath, localePath, routeWithoutLocale, switchesLanguage } from "../i18n";
+import { useTranslations } from "../i18n/ui";
 
 const pathname = Astro.url.pathname;
-const basePath = import.meta.env.BASE_URL;
-const withBase = (path: string) => `${basePath}${path.replace(/^\/+/, "")}`;
+const locale = localeFromPath(pathname);
+const t = useTranslations(locale);
+const href = (path: string) => localePath(bestLocaleFor(locale, path), path);
+/* The security and enterprise pages stay published and linked from the footer,
+   the release index and the demo's preview-gate result — they are just not
+   worth a top-level nav slot. */
 const nav = [
-  { path: "downloads/", label: "下载" },
-  { path: "quickstart/", label: "快速开始" },
-  { path: "agents/", label: "Agent" },
-  { path: "providers/", label: "Provider" },
-  { path: "security/", label: "安全" },
+  { path: "downloads/", label: t("nav.downloads") },
+  { path: "quickstart/", label: t("nav.quickstart") },
+  { path: "explore/", label: t("nav.explorer") },
 ];
-const active = (path: string) => pathname.includes(`/${path}`);
+// Compared on the locale-stripped route so /en/agents/ marks the same item as
+// /agents/ rather than matching on a substring of the full path.
+const route = routeWithoutLocale(pathname);
+const active = (path: string) =>
+  route === path ||
+  (path === "explore/" && (route === "agents/" || route.startsWith("agents/") || route === "providers/" || route.startsWith("providers/")));
 ---
 <header class="site-header">
   <div class="shell header-inner">
-    <a class="wordmark" href={withBase("")} aria-label="OneAgent 首页">
+    <a class="wordmark" href={href("")} aria-label={t("nav.home")}>
       <span class="wordmark-mark"><BrandMark size={24} /></span>
       <span>OneAgent</span>
     </a>
-    <nav class="desktop-nav" aria-label="主导航">
+    <nav class="desktop-nav" aria-label={t("nav.primary")}>
       {nav.map((item) => (
-        <a href={withBase(item.path)} aria-current={active(item.path) ? "page" : undefined}>{item.label}</a>
+        <a href={href(item.path)} aria-current={active(item.path) ? "page" : undefined}>
+          {item.label}
+          {switchesLanguage(locale, item.path) && <span class="lang-hint">{t("nav.chineseOnly")}</span>}
+        </a>
       ))}
     </nav>
     <div class="header-actions">
-      <a class="header-link" href={withBase("enterprise/")}>企业服务</a>
-      <a class="button button-small button-primary" href={withBase("downloads/")}>下载预览版</a>
+      <LocaleSwitch />
+      <ThemeToggle />
+      <a class:list={["button", "button-small", route === "" ? "button-secondary" : "button-primary"]} href={href("downloads/")}>{t("cta.download")}</a>
       <details class="mobile-menu">
-        <summary aria-label="打开导航菜单">菜单</summary>
-        <nav aria-label="移动端导航">
-          {nav.map((item) => <a href={withBase(item.path)}>{item.label}</a>)}
-          <a href={withBase("enterprise/")}>企业服务</a>
-          <a href={withBase("support/")}>支持</a>
+        <summary aria-label={t("nav.openMenu")}>{t("nav.menu")}</summary>
+        <nav aria-label={t("nav.mobile")}>
+          {[...nav, { path: "support/", label: t("nav.support") }].map((item) => (
+            <a href={href(item.path)}>
+              {item.label}
+              {switchesLanguage(locale, item.path) && <span class="lang-hint">{t("nav.chineseOnly")}</span>}
+            </a>
+          ))}
         </nav>
       </details>
     </div>
diff --git a/site/src/components/HeroParticles.astro b/site/src/components/HeroParticles.astro
new file mode 100644
index 00000000..6f442ca4
--- /dev/null
+++ b/site/src/components/HeroParticles.astro
@@ -0,0 +1,132 @@
+---
+---
+<canvas class="hero-particles" data-hero-particles aria-hidden="true"></canvas>
+
+<style>
+  .hero-particles {
+    display: block;
+    width: 100%;
+    height: 100%;
+    position: absolute;
+    inset: 0;
+    z-index: 0;
+    pointer-events: none;
+  }
+</style>
+
+<script>
+  const canvas = document.querySelector<HTMLCanvasElement>("[data-hero-particles]");
+  const context = canvas?.getContext("2d");
+
+  if (canvas && context) {
+    const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const COUNT = 56;
+    const particles: { x: number; y: number; vx: number; vy: number; r: number; a: number }[] = [];
+    let width = 0;
+    let height = 0;
+    let frame = 0;
+
+    const resize = () => {
+      const ratio = Math.min(window.devicePixelRatio || 1, 2);
+      const box = canvas.getBoundingClientRect();
+      width = box.width;
+      height = box.height;
+      canvas.width = Math.round(width * ratio);
+      canvas.height = Math.round(height * ratio);
+      context.setTransform(ratio, 0, 0, ratio, 0, 0);
+    };
+
+    const seed = () => {
+      particles.length = 0;
+      for (let i = 0; i < COUNT; i += 1) {
+        particles.push({
+          x: Math.random() * width,
+          y: Math.random() * height,
+          vx: (Math.random() - 0.5) * 0.18,
+          vy: (Math.random() - 0.5) * 0.18,
+          r: 0.8 + Math.random() * 1.6,
+          a: 0.16 + Math.random() * 0.3,
+        });
+      }
+    };
+
+    // Canvas cannot resolve var() itself, so the theme's channel triple is read
+    // off the element and cached — re-reading it per particle per frame would
+    // force a style recalc 56 times a frame.
+    let channels = "0, 98, 204";
+    const readChannels = () => {
+      const value = getComputedStyle(canvas).getPropertyValue("--particle").trim();
+      if (value) channels = value;
+    };
+
+    const paint = () => {
+      context.clearRect(0, 0, width, height);
+      for (const p of particles) {
+        context.beginPath();
+        context.arc(p.x, p.y, p.r, 0, Math.PI * 2);
+        context.fillStyle = `rgba(${channels}, ${p.a})`;
+        context.fill();
+      }
+    };
+
+    const tick = () => {
+      for (const p of particles) {
+        p.x += p.vx;
+        p.y += p.vy;
+        if (p.x < 0) p.x = width;
+        else if (p.x > width) p.x = 0;
+        if (p.y < 0) p.y = height;
+        else if (p.y > height) p.y = 0;
+      }
+      paint();
+      frame = window.requestAnimationFrame(tick);
+    };
+
+    const stop = () => {
+      if (frame) window.cancelAnimationFrame(frame);
+      frame = 0;
+    };
+
+    // The CSS prefers-reduced-motion block only clamps CSS animations, so the
+    // loop has to opt out on its own: paint one static frame and never start.
+    const start = () => {
+      stop();
+      if (!reduceMotion.matches) frame = window.requestAnimationFrame(tick);
+    };
+
+    resize();
+    readChannels();
+    seed();
+    paint();
+    start();
+
+    // Under reduced motion nothing repaints on its own, so a theme switch has to
+    // trigger the redraw or the particles keep the previous scheme's colour.
+    document.addEventListener("oneagent:themechange", () => {
+      readChannels();
+      if (!frame) paint();
+    });
+
+    new IntersectionObserver((entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) start();
+        else stop();
+      }
+    }).observe(canvas);
+
+    window.addEventListener("resize", () => {
+      resize();
+      seed();
+      paint();
+    });
+
+    reduceMotion.addEventListener("change", () => {
+      if (reduceMotion.matches) {
+        stop();
+        paint();
+      } else {
+        start();
+      }
+    });
+  }
+</script>
diff --git a/site/src/components/LocaleSwitch.astro b/site/src/components/LocaleSwitch.astro
new file mode 100644
index 00000000..7d0800f3
--- /dev/null
+++ b/site/src/components/LocaleSwitch.astro
@@ -0,0 +1,32 @@
+---
+import { localeFromPath, localePath, locales, localeNames, routeWithoutLocale, translatedRoutes } from "../i18n";
+import { useTranslations } from "../i18n/ui";
+
+const current = localeFromPath(Astro.url.pathname);
+const route = routeWithoutLocale(Astro.url.pathname);
+const t = useTranslations(current);
+const target = locales.find((locale) => locale !== current)!;
+// Switching keeps the reader on the same page where that page is translated,
+// and falls back to the home page rather than a 404 where it is not.
+const targetHref = localePath(target, translatedRoutes.has(route) ? route : "");
+---
+<a class="locale-switch" href={targetHref} hreflang={target} lang={target} aria-label={t("lang.switch")}>
+  {localeNames[target]}
+</a>
+
+<style>
+  .locale-switch {
+    min-height: 34px;
+    padding: 0 10px;
+    display: inline-flex;
+    align-items: center;
+    color: var(--ink-soft);
+    border: 1px solid var(--line);
+    border-radius: var(--radius-control);
+    font-size: 13px;
+    font-weight: 560;
+    transition: color var(--dur-micro) var(--ease-apple), background-color var(--dur-micro) var(--ease-apple), border-color var(--dur-micro) var(--ease-apple);
+  }
+  .locale-switch:hover { color: var(--ink); background: var(--surface); border-color: var(--line-strong); }
+  .locale-switch:active { background: var(--surface-pressed); transition-duration: 100ms; }
+</style>
diff --git a/site/src/components/ThemeToggle.astro b/site/src/components/ThemeToggle.astro
new file mode 100644
index 00000000..238f14ae
--- /dev/null
+++ b/site/src/components/ThemeToggle.astro
@@ -0,0 +1,80 @@
+---
+import { localeFromPath } from "../i18n";
+import { useTranslations } from "../i18n/ui";
+
+const t = useTranslations(localeFromPath(Astro.url.pathname));
+const label = t("theme.toggle");
+---
+<button
+  class="theme-toggle"
+  type="button"
+  data-theme-toggle
+  aria-pressed="false"
+  aria-label={label}
+  title={label}
+>
+  <svg class="theme-icon-sun" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round">
+    <circle cx="8" cy="8" r="3.1" />
+    <path d="M8 1.4v1.5M8 13.1v1.5M1.4 8h1.5M13.1 8h1.5M3.3 3.3l1.1 1.1M11.6 11.6l1.1 1.1M12.7 3.3l-1.1 1.1M4.4 11.6l-1.1 1.1" />
+  </svg>
+  <svg class="theme-icon-moon" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round">
+    <path d="M13.4 9.9A5.9 5.9 0 0 1 6.1 2.6a5.9 5.9 0 1 0 7.3 7.3Z" />
+  </svg>
+</button>
+
+<style>
+  .theme-toggle {
+    width: 34px;
+    height: 34px;
+    display: grid;
+    place-items: center;
+    color: var(--ink-soft);
+    background: transparent;
+    border: 1px solid var(--line);
+    border-radius: var(--radius-control);
+    cursor: pointer;
+    transition: color var(--dur-micro) var(--ease-apple), background-color var(--dur-micro) var(--ease-apple), border-color var(--dur-micro) var(--ease-apple);
+  }
+  .theme-toggle:hover { color: var(--ink); background: var(--surface); border-color: var(--line-strong); }
+  .theme-toggle:active { background: var(--surface-pressed); transition-duration: 100ms; }
+  .theme-toggle svg { grid-area: 1 / 1; }
+  /* Only one glyph shows at a time; which one is decided by the theme class the
+     inline head script has already applied, so there is no swap on hydration. */
+  .theme-icon-moon { display: none; }
+  :global(.theme-dark) .theme-icon-sun { display: none; }
+  :global(.theme-dark) .theme-icon-moon { display: block; }
+</style>
+
+<script>
+  const STORAGE_KEY = "oneagent-theme";
+  const button = document.querySelector<HTMLButtonElement>("[data-theme-toggle]");
+  const system = window.matchMedia("(prefers-color-scheme: dark)");
+
+  const isDark = () => document.documentElement.classList.contains("theme-dark");
+
+  const sync = () => {
+    button?.setAttribute("aria-pressed", isDark() ? "true" : "false");
+    document.dispatchEvent(new CustomEvent("oneagent:themechange"));
+  };
+
+  const apply = (dark: boolean) => {
+    document.documentElement.classList.toggle("theme-dark", dark);
+    sync();
+  };
+
+  button?.addEventListener("click", () => {
+    const next = !isDark();
+    // Storing the resolved choice means a later system flip cannot silently
+    // override what the reader picked.
+    window.localStorage.setItem(STORAGE_KEY, next ? "dark" : "light");
+    apply(next);
+  });
+
+  // A system change should still win while no explicit choice is stored.
+  system.addEventListener("change", (event) => {
+    if (window.localStorage.getItem(STORAGE_KEY)) return;
+    apply(event.matches);
+  });
+
+  sync();
+</script>
diff --git a/site/src/i18n/catalog.test.ts b/site/src/i18n/catalog.test.ts
new file mode 100644
index 00000000..f2958c26
--- /dev/null
+++ b/site/src/i18n/catalog.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+
+import { catalog } from "../lib/catalog";
+import { locales, switchesLanguage, translatedRoutes, type Locale } from "./index";
+import { useCatalogLabels } from "./catalog";
+
+
+// Every enum the catalog can emit needs a label in every locale. A missing entry
+// falls back to the raw id, which reads as the wrong language rather than as a
+// bug — the Chinese `gateway` label shipped as the English "Gateway Agent" that
+// way, and nothing failed.
+describe("catalogue labels cover every locale", () => {
+  const cjk = /[一-鿿]/;
+
+  for (const locale of locales) {
+    describe(locale, () => {
+      const labels = useCatalogLabels(locale);
+
+      it("labels every group the catalog uses", () => {
+        const used = [...new Set(catalog.agents.map((agent) => agent.group))].sort();
+        for (const group of used) {
+          expect(labels.groupLabels[group], `${locale} is missing group "${group}"`).toBeTruthy();
+        }
+      });
+
+      it("labels every protocol status the providers publish", () => {
+        const used = [...new Set(catalog.providers.flatMap((p) => p.protocols.map((entry) => entry.status)))].sort();
+        for (const status of used) {
+          expect(labels.protocolStatusLabels[status], `${locale} is missing status "${status}"`).toBeTruthy();
+        }
+      });
+
+      it("writes group labels in the locale's own language", () => {
+        for (const [group, label] of Object.entries(labels.groupLabels)) {
+          // Proper nouns are allowed to stay Latin, so the check is directional:
+          // a Chinese label must contain some Chinese, and an English one none.
+          if (locale === "zh-CN") {
+            expect(cjk.test(label), `zh-CN group "${group}" has no Chinese: ${label}`).toBe(true);
+          } else {
+            expect(cjk.test(label), `en group "${group}" contains Chinese: ${label}`).toBe(false);
+          }
+        }
+      });
+    });
+  }
+});
+
+describe("cross-language link detection", () => {
+  it("flags only the routes with no translation", () => {
+    for (const route of translatedRoutes) {
+      expect(switchesLanguage("en", route), `${route} is translated`).toBe(false);
+    }
+    for (const route of ["enterprise/", "support/", "agents/", "providers/", "changelog/"]) {
+      expect(switchesLanguage("en", route), `${route} has no English page`).toBe(true);
+    }
+  });
+
+  it("never flags a link for a Chinese reader, since Chinese is the fallback", () => {
+    for (const route of [...translatedRoutes, "enterprise/", "agents/"]) {
+      expect(switchesLanguage("zh-CN" as Locale, route)).toBe(false);
+    }
+  });
+});
diff --git a/site/src/i18n/catalog.ts b/site/src/i18n/catalog.ts
new file mode 100644
index 00000000..ccdfe605
--- /dev/null
+++ b/site/src/i18n/catalog.ts
@@ -0,0 +1,75 @@
+import type { Locale } from "./index";
+
+/**
+ * Catalogue enum labels. protocolLabels and platformLabels are absent on
+ * purpose — their values are proper nouns ("OpenAI Chat Completions", "macOS")
+ * and stay in src/lib/content.ts, shared by both languages.
+ */
+const catalog = {
+  "zh-CN": {
+    agentDescriptions: {
+      codex: "OpenAI 的终端编码 Agent，OneAgent 管理 Responses 协议配置。",
+      "claude-code": "Anthropic 的终端编码 Agent，使用 Anthropic-compatible 配置。",
+      cursor: "AI 编辑器；OneAgent 只提供官方安装与登录引导，不写入私有配置。",
+      opencode: "开源终端编码 Agent，使用 OpenAI-compatible 协议。",
+      openclaw: "多渠道 Agent 网关；按官方流程安装、onboard 与管理服务。",
+      hermes: "自我成长型 Agent 框架；模型与运行配置由官方工具管理。",
+      "gemini-cli": "Google 官方 CLI；使用 Google 登录、Gemini API Key 或 Vertex AI。",
+      "kilo-cli": "多模型命令行 Agent，OneAgent 可管理安装与 OpenAI-compatible 配置。",
+      aider: "结对编程式仓库编辑 Agent，模型在启动命令中明确选择。",
+      kiro: "官方账号型开发 Agent；使用官方登录与配置流程。",
+      cline: "IDE 扩展；在扩展界面选择兼容 Provider。",
+      continue: "IDE 扩展；在 Continue 配置中添加兼容模型。",
+      "qwen-code": "Qwen 的编码工具；按官方文档完成安装和 Provider 配置。",
+      "kilo-vscode": "Kilo Code 的 VS Code 扩展；由扩展界面管理 Provider。",
+    } as Record<string, string>,
+    groupLabels: {
+      auto: "OneAgent 可管理",
+      gateway: "网关 Agent",
+      platform: "官方账号 Agent",
+      ide: "IDE 扩展",
+    } as Record<string, string>,
+    protocolStatusLabels: {
+      "implementation-supported": "实现已接入",
+      "release-candidate-required": "需 Release Candidate 实证",
+      verified: "已验证",
+      unsupported: "不支持",
+    } as Record<string, string>,
+    agentFallbackDescription: "按项目公开能力提供安装或配置支持。",
+  },
+  en: {
+    agentDescriptions: {
+      codex: "OpenAI's terminal coding agent; OneAgent manages its Responses protocol configuration.",
+      "claude-code": "Anthropic's terminal coding agent, configured through an Anthropic-compatible endpoint.",
+      cursor: "AI editor. OneAgent only points you at the official install and sign-in, and writes no private config.",
+      opencode: "Open-source terminal coding agent using the OpenAI-compatible protocol.",
+      openclaw: "Multi-channel agent gateway; install, onboard and run it through the official flow.",
+      hermes: "Self-improving agent framework; its own tooling owns model and runtime configuration.",
+      "gemini-cli": "Google's official CLI, using Google sign-in, a Gemini API key or Vertex AI.",
+      "kilo-cli": "Multi-model command-line agent. OneAgent can manage both install and OpenAI-compatible config.",
+      aider: "Pair-programming repository editor; the model is named explicitly at launch.",
+      kiro: "Account-based development agent using the vendor's own sign-in and configuration.",
+      cline: "IDE extension; choose a compatible provider inside the extension.",
+      continue: "IDE extension; add a compatible model in Continue's own configuration.",
+      "qwen-code": "Qwen's coding tool; follow the official docs for install and provider setup.",
+      "kilo-vscode": "Kilo Code's VS Code extension; providers are managed in the extension UI.",
+    } as Record<string, string>,
+    groupLabels: {
+      auto: "OneAgent-managed",
+      gateway: "Gateway agent",
+      platform: "Vendor-account agent",
+      ide: "IDE extension",
+    } as Record<string, string>,
+    protocolStatusLabels: {
+      "implementation-supported": "Implemented",
+      "release-candidate-required": "Needs release-candidate evidence",
+      verified: "Verified",
+      unsupported: "Unsupported",
+    } as Record<string, string>,
+    agentFallbackDescription: "Install or configuration support follows the project's published capabilities.",
+  },
+} as const;
+
+export function useCatalogLabels(locale: Locale) {
+  return catalog[locale];
+}
diff --git a/site/src/i18n/index.ts b/site/src/i18n/index.ts
new file mode 100644
index 00000000..aaa84595
--- /dev/null
+++ b/site/src/i18n/index.ts
@@ -0,0 +1,70 @@
+export const locales = ["zh-CN", "en"] as const;
+export type Locale = (typeof locales)[number];
+export const defaultLocale: Locale = "zh-CN";
+
+/** Prefix carried in the URL for each locale; the default locale has none. */
+const prefixes: Record<Locale, string> = { "zh-CN": "", en: "en" };
+
+export const htmlLang: Record<Locale, string> = { "zh-CN": "zh-CN", en: "en" };
+export const ogLocale: Record<Locale, string> = { "zh-CN": "zh_CN", en: "en_US" };
+export const localeNames: Record<Locale, string> = { "zh-CN": "中文", en: "English" };
+
+const base = import.meta.env.BASE_URL;
+const baseSegments = base.split("/").filter(Boolean);
+
+/**
+ * Reads the locale out of a pathname. Works under a configured base path, where
+ * the locale segment is not the first one.
+ */
+export function localeFromPath(pathname: string): Locale {
+  const segments = pathname.split("/").filter(Boolean).slice(baseSegments.length);
+  const candidate = segments[0];
+  const match = locales.find((locale) => prefixes[locale] && prefixes[locale] === candidate);
+  return match ?? defaultLocale;
+}
+
+/**
+ * Builds an absolute, locale-aware path.
+ *
+ * Every link has to go through this. Relative hrefs resolve against <base>,
+ * which knows nothing about locales, so a relative link on an English page
+ * silently lands on the Chinese one — and validate-build.mjs anchors its
+ * link check at the root, so it cannot see that happen.
+ */
+export function localePath(locale: Locale, path = ""): string {
+  const clean = path.replace(/^\/+/, "");
+  const prefix = prefixes[locale];
+  return `${base}${prefix ? `${prefix}/` : ""}${clean}`;
+}
+
+/**
+ * Routes that exist in every locale. Anything outside this set is Chinese-only
+ * for now, and linking it under /en/ would point at a path that was never built
+ * — which validate-build.mjs fails the build over. Add a route here in the same
+ * change that adds its translation.
+ */
+export const translatedRoutes = new Set(["", "downloads/", "quickstart/", "explore/", "security/"]);
+
+/** Resolves a link to the current locale when translated, Chinese otherwise. */
+export function bestLocaleFor(locale: Locale, route: string): Locale {
+  return translatedRoutes.has(route) ? locale : defaultLocale;
+}
+
+/**
+ * True when following this link from `locale` lands on a different language.
+ *
+ * Untranslated routes fall back to Chinese, which is better than a 404 but is a
+ * surprise if nothing says so first. Callers use this to mark the link, so the
+ * language change is visible before the click rather than after it.
+ */
+export function switchesLanguage(locale: Locale, route: string): boolean {
+  return bestLocaleFor(locale, route) !== locale;
+}
+
+/** Strips base and locale, yielding the route shared across languages. */
+export function routeWithoutLocale(pathname: string): string {
+  const segments = pathname.split("/").filter(Boolean).slice(baseSegments.length);
+  const first = segments[0];
+  if (locales.some((locale) => prefixes[locale] && prefixes[locale] === first)) segments.shift();
+  return segments.length ? `${segments.join("/")}/` : "";
+}
diff --git a/site/src/i18n/ui.ts b/site/src/i18n/ui.ts
new file mode 100644
index 00000000..b6b94480
--- /dev/null
+++ b/site/src/i18n/ui.ts
@@ -0,0 +1,86 @@
+import type { Locale } from "./index";
+
+/**
+ * Chrome and shared-component copy. Page prose stays in the page templates —
+ * only strings reused across pages, or read by more than one component, belong
+ * here.
+ */
+const strings = {
+  "zh-CN": {
+    "site.title": "OneAgent — 可信的本地 AI 开发环境激活器",
+    "site.description": "用一个可信的本地流程，激活你自己的 Agent、账号和 Provider。",
+    "skip.main": "跳到主要内容",
+    "nav.home": "OneAgent 首页",
+    "nav.downloads": "下载",
+    "nav.quickstart": "快速开始",
+    "nav.explorer": "配置",
+    "nav.agents": "Agent",
+    "nav.providers": "Provider",
+    "nav.support": "支持",
+    "nav.changelog": "更新日志",
+    "nav.primary": "主导航",
+    "nav.mobile": "移动端导航",
+    "nav.openMenu": "打开导航菜单",
+    /* Only ever shown on an English page, where it warns that the target has no
+       translation yet. A Chinese reader never sees it, but the key exists in both
+       dictionaries so useTranslations stays exhaustive. */
+    "nav.chineseOnly": "仅中文",
+    "nav.menu": "菜单",
+    "cta.download": "下载预览版",
+    "theme.toggle": "切换深色模式",
+    "lang.switch": "切换语言",
+    "breadcrumb.label": "面包屑",
+    "breadcrumb.home": "首页",
+    "footer.tagline": "可信的本地 AI 开发环境激活器。",
+    "footer.boundary": "不提供共享 Key，不代理模型请求，不重新分发第三方 Agent。",
+    "footer.start": "开始",
+    "footer.capability": "能力",
+    "footer.trust": "信任",
+    "footer.downloadCenter": "下载中心",
+    "footer.agentCatalog": "Agent 兼容目录",
+    "footer.providerCatalog": "Provider 目录",
+    "footer.supportFeedback": "支持与反馈",
+    "footer.releaseIndex": "GitHub Releases",
+    "footer.channel": "当前公开渠道：technical-preview-unsigned",
+  },
+  en: {
+    "site.title": "OneAgent — a trustworthy local AI development environment activator",
+    "site.description": "Activate your own agents, accounts and providers through one auditable local flow.",
+    "skip.main": "Skip to main content",
+    "nav.home": "OneAgent home",
+    "nav.downloads": "Downloads",
+    "nav.quickstart": "Quickstart",
+    "nav.explorer": "Explorer",
+    "nav.agents": "Agents",
+    "nav.providers": "Providers",
+    "nav.support": "Support",
+    "nav.changelog": "Changelog",
+    "nav.primary": "Primary navigation",
+    "nav.mobile": "Mobile navigation",
+    "nav.openMenu": "Open navigation menu",
+    "nav.chineseOnly": "in Chinese",
+    "nav.menu": "Menu",
+    "cta.download": "Get the preview",
+    "theme.toggle": "Toggle dark mode",
+    "lang.switch": "Change language",
+    "breadcrumb.label": "Breadcrumb",
+    "breadcrumb.home": "Home",
+    "footer.tagline": "A trustworthy local AI development environment activator.",
+    "footer.boundary": "No shared keys, no proxied model requests, no redistribution of third-party agents.",
+    "footer.start": "Start",
+    "footer.capability": "Capabilities",
+    "footer.trust": "Trust",
+    "footer.downloadCenter": "Download centre",
+    "footer.agentCatalog": "Agent compatibility",
+    "footer.providerCatalog": "Provider catalogue",
+    "footer.supportFeedback": "Support & feedback",
+    "footer.releaseIndex": "GitHub Releases",
+    "footer.channel": "Current public channel: technical-preview-unsigned",
+  },
+} as const;
+
+export type UIKey = keyof (typeof strings)["zh-CN"];
+
+export function useTranslations(locale: Locale) {
+  return (key: UIKey): string => strings[locale][key] ?? strings["zh-CN"][key];
+}
diff --git a/site/src/layouts/BaseLayout.astro b/site/src/layouts/BaseLayout.astro
index 5b01e89f..6720b816 100644
--- a/site/src/layouts/BaseLayout.astro
+++ b/site/src/layouts/BaseLayout.astro
@@ -1,7 +1,9 @@
 ---
 import Header from "../components/Header.astro";
 import Footer from "../components/Footer.astro";
-import releaseIndexData from "../generated/release-index.json";
+import { defaultLocale, htmlLang, localeFromPath, localePath, locales, ogLocale, routeWithoutLocale, translatedRoutes } from "../i18n";
+import { useTranslations } from "../i18n/ui";
+import { getPreviewChannel } from "../lib/release-channel";
 import "../styles/global.css";
 
 interface Props {
@@ -11,16 +13,29 @@ interface Props {
   noindex?: boolean;
 }
 
+const locale = localeFromPath(Astro.url.pathname);
+const t = useTranslations(locale);
 const {
-  title = "OneAgent — 可信的本地 AI 开发环境激活器",
-  description = "用一个可信的本地流程，激活你自己的 Agent、账号和 Provider。",
+  title = t("site.title"),
+  description = t("site.description"),
   image = "images/oneagent-overview.jpg",
   noindex = false,
 } = Astro.props;
-const canonical = new URL(Astro.url.pathname, Astro.site ?? Astro.url.origin);
-const baseUrl = new URL(import.meta.env.BASE_URL, Astro.site ?? Astro.url.origin);
-const imageUrl = new URL(image.replace(/^\/+/, ""), baseUrl);
-const preview = releaseIndexData.channels.find((channel) => channel.channel === "technical-preview-unsigned");
+const canonicalOrigin = Astro.site ?? Astro.url.origin;
+const canonical = new URL(Astro.url.pathname, canonicalOrigin);
+// Only pages that exist in both languages get alternates; pointing hreflang at
+// an unbuilt path would advertise a 404 to crawlers.
+const route = routeWithoutLocale(Astro.url.pathname);
+const alternates = translatedRoutes.has(route)
+  ? locales.map((code) => ({
+      code,
+      href: new URL(localePath(code, route), canonicalOrigin).toString(),
+    }))
+  : [];
+const runtimeBaseUrl = new URL(import.meta.env.BASE_URL, Astro.url.origin);
+const canonicalBaseUrl = new URL(import.meta.env.BASE_URL, canonicalOrigin);
+const imageUrl = new URL(image.replace(/^\/+/, ""), canonicalBaseUrl);
+const preview = await getPreviewChannel();
 const availableSystems = preview?.targets
   .filter((target) => target.status === "available")
   .map((target) => `${target.platformLabel} ${target.archLabel}`) ?? [];
@@ -37,7 +52,7 @@ const structuredData = {
 };
 ---
 <!doctype html>
-<html lang="zh-CN">
+<html lang={htmlLang[locale]}>
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -46,13 +61,40 @@ const structuredData = {
       content="default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-src 'none'; worker-src 'none'"
     />
     <meta name="description" content={description} />
-    <meta name="theme-color" content="#f4f3ef" />
+    <meta name="theme-color" content="#ececef" media="(prefers-color-scheme: light)" />
+    <meta name="theme-color" content="#0f1418" media="(prefers-color-scheme: dark)" />
+    {/* Runs before first paint and before the stylesheet, so the resolved theme
+        is on <html> by the time anything is drawn. Deferring this to the module
+        script would paint the light palette first and flash. */}
+    <script is:inline>
+      (function () {
+        try {
+          var stored = window.localStorage.getItem("oneagent-theme");
+          var dark = stored ? stored === "dark" : window.matchMedia("(prefers-color-scheme: dark)").matches;
+          if (dark) document.documentElement.classList.add("theme-dark");
+        } catch (error) {
+          /* Private mode can throw on localStorage; the light default is fine. */
+        }
+      })();
+    </script>
     {noindex && <meta name="robots" content="noindex" />}
-    <base href={baseUrl.toString()} />
+    <base href={runtimeBaseUrl.toString()} />
     <link rel="canonical" href={canonical} />
+    {alternates.map((alternate) => (
+      <link rel="alternate" hreflang={alternate.code} href={alternate.href} />
+    ))}
+    {alternates.length > 0 && (
+      <link
+        rel="alternate"
+        hreflang="x-default"
+        href={alternates.find((alternate) => alternate.code === defaultLocale)!.href}
+      />
+    )}
     <link rel="icon" href="favicon.svg" type="image/svg+xml" />
+    <link rel="manifest" href="site.webmanifest" />
+    <link rel="alternate" type="text/plain" href="llms.txt" title="llms.txt" />
     <meta property="og:type" content="website" />
-    <meta property="og:locale" content="zh_CN" />
+    <meta property="og:locale" content={ogLocale[locale]} />
     <meta property="og:site_name" content="OneAgent" />
     <meta property="og:title" content={title} />
     <meta property="og:description" content={description} />
@@ -63,7 +105,7 @@ const structuredData = {
     <script type="application/ld+json" is:inline set:html={JSON.stringify(structuredData)} />
   </head>
   <body>
-    <a class="skip-link" href="#main">跳到主要内容</a>
+    <a class="skip-link" href="#main">{t("skip.main")}</a>
     <Header />
     <main id="main"><slot /></main>
     <Footer />
diff --git a/site/src/lib/activation.test.ts b/site/src/lib/activation.test.ts
new file mode 100644
index 00000000..28671419
--- /dev/null
+++ b/site/src/lib/activation.test.ts
@@ -0,0 +1,268 @@
+import { describe, expect, it } from "vitest";
+
+import { CUSTOM_PROVIDER_ID, activationReducer, initialActivationState, validateDemoBaseUrl } from "./activation";
+import type { SiteCatalogV2 } from "./explorer";
+import { DEMO_AGENT_STATES, demoModelsFor, missingDemoAgentIds } from "./demo-environment";
+
+const catalog: SiteCatalogV2 = {
+  schema_version: 2,
+  groups: [{ id: "auto", name: "Auto" }, { id: "ide", name: "IDE" }],
+  agents: [
+    {
+      id: "managed",
+      name: "Managed",
+      group: "auto",
+      rank: 1,
+      command: "managed",
+      configPath: ".managed/config",
+      platforms: ["macos"],
+      lockedVersion: "1.0.0",
+      source: null,
+      license: null,
+      licenseUrl: null,
+      guide: null,
+      protocol: "anthropic",
+      support: { managedInstall: true, officialInstallGuide: false, managedConfig: true },
+    },
+    {
+      id: "preview",
+      name: "Preview",
+      group: "auto",
+      rank: 2,
+      command: "preview",
+      configPath: ".preview/config",
+      platforms: ["macos"],
+      lockedVersion: "1.0.0",
+      source: null,
+      license: null,
+      licenseUrl: null,
+      guide: null,
+      protocol: "responses",
+      support: { managedInstall: true, officialInstallGuide: false, managedConfig: true },
+    },
+    {
+      id: "guided",
+      name: "Guided",
+      group: "ide",
+      rank: 3,
+      command: null,
+      configPath: null,
+      platforms: ["macos"],
+      lockedVersion: null,
+      source: null,
+      license: null,
+      licenseUrl: null,
+      guide: "Use the official flow.",
+      protocol: null,
+      support: { managedInstall: false, officialInstallGuide: true, managedConfig: false },
+    },
+  ],
+  providers: [
+    {
+      id: "provider",
+      name: "Provider",
+      home: "https://provider.example/",
+      relationship: "none",
+      disclosure: "",
+      referralUrl: "",
+      order: 1,
+      protocols: [
+        { id: "anthropic", status: "implementation-supported" },
+        { id: "responses", status: "release-candidate-required" },
+      ],
+    },
+  ],
+};
+
+function scanned() {
+  return activationReducer(
+    activationReducer(initialActivationState(), { type: "start" }, catalog),
+    { type: "scan-complete" },
+    catalog,
+  );
+}
+
+describe("activation demo state machine", () => {
+  it("moves a supported managed combination to ready", () => {
+    let state = scanned();
+    state = activationReducer(state, { type: "select-agent", agentId: "managed" }, catalog);
+    state = activationReducer(state, { type: "select-mode", mode: "provider" }, catalog);
+    state = activationReducer(state, { type: "select-provider", providerId: "provider" }, catalog);
+    state = activationReducer(state, { type: "verify" }, catalog);
+    state = activationReducer(state, { type: "verify-complete" }, catalog);
+    state = activationReducer(state, { type: "select-model", model: "deepseek/deepseek-v3" }, catalog);
+    state = activationReducer(state, { type: "confirm" }, catalog);
+
+    expect(state).toMatchObject({ phase: "ready", agentId: "managed", providerId: "provider", compatibility: "supported" });
+  });
+
+  it("never upgrades release-candidate-required support to ready", () => {
+    let state = scanned();
+    state = activationReducer(state, { type: "select-agent", agentId: "preview" }, catalog);
+    state = activationReducer(state, { type: "select-mode", mode: "provider" }, catalog);
+    state = activationReducer(state, { type: "select-provider", providerId: "provider" }, catalog);
+    state = activationReducer(state, { type: "verify" }, catalog);
+    state = activationReducer(state, { type: "verify-complete" }, catalog);
+
+    expect(state.phase).toBe("preview-gate");
+    // Nothing downstream may rescue a gated combination.
+    expect(activationReducer(state, { type: "confirm" }, catalog).phase).toBe("preview-gate");
+  });
+
+  it("routes guide-only agents without asking for a provider", () => {
+    const state = activationReducer(scanned(), { type: "select-agent", agentId: "guided" }, catalog);
+
+    expect(state).toMatchObject({ phase: "guide-only", agentId: "guided", providerId: null });
+  });
+
+  it("resets every terminal state without retaining a selection", () => {
+    const state = activationReducer(
+      {
+        phase: "error",
+        agentId: "managed",
+        configMode: "provider",
+        providerId: "provider",
+        customBaseUrl: "https://api.example.com",
+        model: "deepseek/deepseek-v3",
+        compatibility: "supported",
+      },
+      { type: "reset" },
+      catalog,
+    );
+
+    expect(state).toEqual(initialActivationState());
+  });
+});
+
+describe("demo environment fixture", () => {
+  it("references only real catalog agents", async () => {
+    const realCatalog = (await import("./catalog")).catalog;
+    expect(missingDemoAgentIds(realCatalog, DEMO_AGENT_STATES)).toEqual([]);
+  });
+
+  it("offers a model list for every provider the real catalog publishes", async () => {
+    const realCatalog = (await import("./catalog")).catalog;
+    for (const provider of realCatalog.providers) {
+      expect(demoModelsFor(provider.id).length, `${provider.id} has no demo models`).toBeGreaterThan(0);
+    }
+  });
+});
+
+// These mirror validate_base_url in oneagent/providers.py. If the kernel's rules
+// change, this suite should fail — the demo claiming an endpoint is acceptable
+// when the product would reject it is the failure mode worth catching.
+describe("custom endpoint validation matches the kernel", () => {
+  it("accepts http and https and strips trailing slashes", () => {
+    expect(validateDemoBaseUrl("https://api.example.com/openai")).toEqual({
+      ok: true,
+      value: "https://api.example.com/openai",
+    });
+    expect(validateDemoBaseUrl("http://localhost:8080/v1//")).toEqual({
+      ok: true,
+      value: "http://localhost:8080/v1",
+    });
+  });
+
+  it("rejects an empty value", () => {
+    expect(validateDemoBaseUrl("")).toEqual({ ok: false, reason: "required" });
+  });
+
+  it("rejects a scheme the kernel does not allow", () => {
+    for (const value of ["ftp://api.example.com", "file:///etc/passwd", "api.example.com", "://nohost"]) {
+      expect(validateDemoBaseUrl(value).ok, value).toBe(false);
+    }
+    expect(validateDemoBaseUrl("ftp://api.example.com")).toEqual({ ok: false, reason: "scheme" });
+  });
+
+  it("rejects credentials embedded in the URL", () => {
+    expect(validateDemoBaseUrl("https://user:secret@api.example.com")).toEqual({
+      ok: false,
+      reason: "credentials",
+    });
+    expect(validateDemoBaseUrl("https://user@api.example.com")).toEqual({ ok: false, reason: "credentials" });
+  });
+
+  it("rejects control characters", () => {
+    // Written as escapes on purpose: a literal newline, tab or DEL in the source
+    // is invisible to a reviewer and an editor may silently normalise it away.
+    for (const value of [
+      "https://api.example.com/\nopenai",
+      "https://api.example.com/\topenai",
+      "https://api.example.com/\u007f",
+      "https://api.example.com/\u0000",
+    ]) {
+      expect(validateDemoBaseUrl(value), JSON.stringify(value)).toEqual({
+        ok: false,
+        reason: "control-characters",
+      });
+    }
+  });
+});
+
+describe("configuration mode branches", () => {
+  const atMode = () => activationReducer(scanned(), { type: "select-agent", agentId: "managed" }, catalog);
+
+  it("asks how to configure before asking for a provider", () => {
+    expect(atMode()).toMatchObject({ phase: "mode", agentId: "managed", configMode: null });
+  });
+
+  it("skips provider and model when an existing account is reused", () => {
+    const state = activationReducer(atMode(), { type: "select-mode", mode: "existing-account" }, catalog);
+
+    expect(state).toMatchObject({
+      phase: "ready",
+      configMode: "existing-account",
+      providerId: null,
+      model: null,
+    });
+  });
+
+  it("requires a verified connection before a model can be chosen", () => {
+    let state = activationReducer(atMode(), { type: "select-mode", mode: "provider" }, catalog);
+    state = activationReducer(state, { type: "select-provider", providerId: "provider" }, catalog);
+    state = activationReducer(state, { type: "verify" }, catalog);
+    state = activationReducer(state, { type: "verify-complete" }, catalog);
+
+    expect(state.phase).toBe("model");
+    // Confirming without a model must not reach ready.
+    expect(activationReducer(state, { type: "confirm" }, catalog).phase).toBe("model");
+
+    state = activationReducer(state, { type: "select-model", model: "deepseek/deepseek-v3" }, catalog);
+    expect(activationReducer(state, { type: "confirm" }, catalog)).toMatchObject({
+      phase: "ready",
+      model: "deepseek/deepseek-v3",
+    });
+  });
+});
+
+describe("custom provider path", () => {
+  const atProvider = () => {
+    let state = activationReducer(scanned(), { type: "select-agent", agentId: "managed" }, catalog);
+    state = activationReducer(state, { type: "select-mode", mode: "provider" }, catalog);
+    return activationReducer(state, { type: "select-provider", providerId: CUSTOM_PROVIDER_ID }, catalog);
+  };
+
+  it("holds at the provider step until the endpoint validates", () => {
+    let state = activationReducer(atProvider(), { type: "set-custom-base-url", value: "not-a-url" }, catalog);
+    expect(activationReducer(state, { type: "verify" }, catalog).phase).toBe("provider");
+
+    state = activationReducer(state, { type: "set-custom-base-url", value: "https://api.example.com/openai" }, catalog);
+    expect(activationReducer(state, { type: "verify" }, catalog).phase).toBe("verifying");
+  });
+
+  it("ignores an endpoint typed against a built-in provider", () => {
+    let state = activationReducer(scanned(), { type: "select-agent", agentId: "managed" }, catalog);
+    state = activationReducer(state, { type: "select-mode", mode: "provider" }, catalog);
+    state = activationReducer(state, { type: "select-provider", providerId: "provider" }, catalog);
+    state = activationReducer(state, { type: "set-custom-base-url", value: "https://elsewhere.example" }, catalog);
+
+    expect(state.customBaseUrl).toBe("");
+  });
+
+  it("clears a typed endpoint when switching back to a built-in provider", () => {
+    let state = activationReducer(atProvider(), { type: "set-custom-base-url", value: "https://api.example.com" }, catalog);
+    state = activationReducer(state, { type: "select-provider", providerId: "provider" }, catalog);
+
+    expect(state).toMatchObject({ providerId: "provider", customBaseUrl: "" });
+  });
+});
diff --git a/site/src/lib/activation.ts b/site/src/lib/activation.ts
new file mode 100644
index 00000000..98defa88
--- /dev/null
+++ b/site/src/lib/activation.ts
@@ -0,0 +1,172 @@
+import { compatibilityFor, type Compatibility, type SiteCatalogV2 } from "./explorer";
+
+export type ActivationPhase =
+  | "idle"
+  | "scanning"
+  | "agent"
+  | "mode"
+  | "provider"
+  | "model"
+  | "verifying"
+  | "ready"
+  | "guide-only"
+  | "preview-gate"
+  | "unsupported"
+  | "error";
+
+/* Mirrors the product's two ConfigModePage choices. "existing-account" is the
+   real branch for a user who already has a subscription or a working config —
+   it skips the provider and model steps, exactly as SetupGuard does. */
+export type ConfigMode = "provider" | "existing-account";
+
+export const CUSTOM_PROVIDER_ID = "custom";
+
+export interface ActivationState {
+  phase: ActivationPhase;
+  agentId: string | null;
+  configMode: ConfigMode | null;
+  providerId: string | null;
+  customBaseUrl: string;
+  model: string | null;
+  compatibility: Compatibility | null;
+}
+
+export type ActivationAction =
+  | { type: "start" }
+  | { type: "scan-complete" }
+  | { type: "select-agent"; agentId: string }
+  | { type: "select-mode"; mode: ConfigMode }
+  | { type: "select-provider"; providerId: string }
+  | { type: "set-custom-base-url"; value: string }
+  | { type: "select-model"; model: string }
+  | { type: "verify" }
+  | { type: "verify-complete" }
+  | { type: "confirm" }
+  | { type: "fail" }
+  | { type: "reset" };
+
+export function initialActivationState(): ActivationState {
+  return {
+    phase: "idle",
+    agentId: null,
+    configMode: null,
+    providerId: null,
+    customBaseUrl: "",
+    model: null,
+    compatibility: null,
+  };
+}
+
+export type BaseUrlRejection =
+  | "required"
+  | "control-characters"
+  | "scheme"
+  | "credentials";
+
+export type BaseUrlCheck =
+  | { ok: true; value: string }
+  | { ok: false; reason: BaseUrlRejection };
+
+/* A line-for-line port of validate_base_url in oneagent/providers.py, in the
+   same order, so the demo rejects exactly what the kernel would reject. The
+   demo is only worth showing if this agrees with the product; a looser check
+   here would teach visitors an endpoint is acceptable when it is not. */
+export function validateDemoBaseUrl(value: string): BaseUrlCheck {
+  if (!value) return { ok: false, reason: "required" };
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code < 32 || code === 127) return { ok: false, reason: "control-characters" };
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return { ok: false, reason: "scheme" };
+  }
+  if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") || !parsed.host) {
+    return { ok: false, reason: "scheme" };
+  }
+  if (parsed.username || parsed.password) return { ok: false, reason: "credentials" };
+  return { ok: true, value: value.replace(/\/+$/, "") };
+}
+
+function errorState(state: ActivationState): ActivationState {
+  return { ...state, phase: "error" };
+}
+
+export function activationReducer(
+  state: ActivationState,
+  action: ActivationAction,
+  catalog: SiteCatalogV2,
+): ActivationState {
+  if (action.type === "reset") return initialActivationState();
+
+  switch (action.type) {
+    case "start":
+      return state.phase === "idle" ? { ...initialActivationState(), phase: "scanning" } : state;
+    case "scan-complete":
+      return state.phase === "scanning" ? { ...state, phase: "agent" } : state;
+    case "select-agent": {
+      const agent = catalog.agents.find((candidate) => candidate.id === action.agentId);
+      if (!agent) return errorState(state);
+      const base = { ...initialActivationState(), agentId: agent.id };
+      if (agent.support.officialInstallGuide || !agent.support.managedConfig || !agent.protocol) {
+        return { ...base, phase: "guide-only" };
+      }
+      return { ...base, phase: "mode" };
+    }
+    case "select-mode": {
+      if (state.phase !== "mode" || !state.agentId) return state;
+      /* Picking an existing account ends the demo at the same place the product
+         lands: nothing to verify, because no new credential is being introduced. */
+      if (action.mode === "existing-account") {
+        return { ...state, phase: "ready", configMode: action.mode, providerId: null, model: null, compatibility: null };
+      }
+      return { ...state, phase: "provider", configMode: action.mode };
+    }
+    case "select-provider": {
+      const agent = catalog.agents.find((candidate) => candidate.id === state.agentId);
+      if (!agent) return errorState(state);
+      /* A custom endpoint has no catalog entry, so there is no published
+         protocol status to read. The product treats it as usable-but-unproven:
+         the probe decides, which here means the demo's own verify step. */
+      if (action.providerId === CUSTOM_PROVIDER_ID) {
+        return { ...state, phase: "provider", providerId: CUSTOM_PROVIDER_ID, compatibility: "supported" };
+      }
+      const provider = catalog.providers.find((candidate) => candidate.id === action.providerId);
+      if (!provider) return errorState(state);
+      const compatibility = compatibilityFor(agent, provider);
+      if (compatibility === "unsupported") {
+        return { ...state, phase: "unsupported", providerId: provider.id, customBaseUrl: "", compatibility };
+      }
+      return { ...state, phase: "provider", providerId: provider.id, customBaseUrl: "", compatibility };
+    }
+    case "set-custom-base-url":
+      return state.providerId === CUSTOM_PROVIDER_ID ? { ...state, customBaseUrl: action.value } : state;
+    case "select-model":
+      return state.phase === "model" && action.model ? { ...state, model: action.model } : state;
+    case "verify": {
+      if (state.phase !== "provider" || !state.agentId || !state.providerId || !state.compatibility) {
+        return errorState(state);
+      }
+      // An unvalidated endpoint must not reach verification, the same way the
+      // product's probe button stays disabled until a custom base URL parses.
+      if (state.providerId === CUSTOM_PROVIDER_ID && !validateDemoBaseUrl(state.customBaseUrl).ok) {
+        return state;
+      }
+      return { ...state, phase: "verifying" };
+    }
+    case "verify-complete":
+      if (state.phase !== "verifying") return state;
+      if (state.compatibility === "preview-gate") return { ...state, phase: "preview-gate" };
+      if (state.compatibility === "supported" || state.compatibility === "verified") {
+        // Verification unlocks model choice; it is not the end of the flow.
+        return { ...state, phase: "model" };
+      }
+      return { ...state, phase: "unsupported" };
+    case "confirm":
+      return state.phase === "model" && state.model ? { ...state, phase: "ready" } : state;
+    case "fail":
+      return errorState(state);
+  }
+}
diff --git a/site/src/lib/catalog.ts b/site/src/lib/catalog.ts
new file mode 100644
index 00000000..2e6a7530
--- /dev/null
+++ b/site/src/lib/catalog.ts
@@ -0,0 +1,114 @@
+import agentLock from "../../../agents.lock.json";
+import providerConfig from "../../../providers.lock.json";
+/* The site-facing shapes are declared once, in explorer.ts, because the explorer
+   is what constrains them: it narrows platforms and protocols to the ids it can
+   actually render a compatibility verdict for. Re-declaring them here would let
+   a new protocol reach the pages while the explorer silently calls it
+   unsupported. */
+import type { PlatformId, ProtocolId, SiteAgent, SiteCatalogV2, SiteProvider, ProviderProtocolStatus } from "./explorer";
+
+const adapterProtocols: Record<string, ProtocolId> = {
+  codex: "responses",
+  "claude-code": "anthropic",
+  opencode: "openai",
+  "kilo-cli": "openai",
+  aider: "openai",
+};
+
+interface AgentSource {
+  name?: string;
+  group?: string;
+  rank?: number;
+  platforms?: string[];
+  command?: string;
+  config_mode: "auto" | "guide";
+  config_adapter?: string;
+  config_path?: string;
+  guide?: string;
+  package?: {
+    version?: string;
+    source?: string;
+    license?: string;
+    license_url?: string;
+  };
+}
+
+/* The group ids come from agents.lock.json, but the labels do not live there —
+   the lock file is the installer's contract and has no room for display copy.
+   Anything not listed falls back to its own id, so a new group appears on the
+   site as soon as it appears in the lock rather than vanishing from the list. */
+const groupNames: Record<string, string> = {
+  auto: "One-click configurable",
+  gateway: "Gateway agents",
+  platform: "Official account agents",
+  ide: "IDE extensions",
+};
+
+interface ProviderSource {
+  name?: string;
+  home: string;
+  relationship?: "none" | "referral" | "sponsor";
+  disclosure?: string;
+  referral_url?: string;
+  order?: number;
+  protocols?: Record<string, string>;
+}
+
+
+const agents = Object.entries(agentLock.agents as Record<string, AgentSource>)
+  .map(([id, meta]): SiteAgent => {
+    const managedConfig = meta.config_mode === "auto" && Boolean(meta.config_adapter);
+    return {
+      id,
+      name: meta.name ?? id,
+      group: meta.group ?? "other",
+      rank: meta.rank ?? 99,
+      /* Both are shown on the site so a reader can check what OneAgent will run
+         and which file it will write before installing anything. guide-only
+         agents have neither, and null keeps that visible rather than printing an
+         empty string that looks like a missing value. */
+      command: meta.command ?? null,
+      configPath: meta.config_path ?? null,
+      platforms: (meta.platforms ?? []) as PlatformId[],
+      lockedVersion: meta.package?.version ?? null,
+      source: meta.package?.source ?? null,
+      license: meta.package?.license ?? null,
+      licenseUrl: meta.package?.license_url ?? null,
+      guide: meta.guide ?? null,
+      protocol: managedConfig ? adapterProtocols[meta.config_adapter!] ?? null : null,
+
+      support: {
+        managedInstall: meta.config_mode === "auto" && Boolean(meta.package),
+        officialInstallGuide: meta.config_mode === "guide",
+        managedConfig,
+      },
+    };
+  })
+  .sort((left, right) => left.rank - right.rank || left.id.localeCompare(right.id));
+
+const providers = Object.entries(providerConfig.providers as Record<string, ProviderSource>)
+  .map(([id, meta]): SiteProvider => ({
+    id,
+    name: meta.name ?? id,
+    home: meta.home,
+    relationship: meta.relationship ?? "none",
+    disclosure: meta.disclosure ?? "",
+    referralUrl: meta.referral_url ?? "",
+    protocols: Object.entries(meta.protocols ?? {}).map(([protocolId, status]) => ({
+      id: protocolId as ProtocolId,
+      status: status as ProviderProtocolStatus,
+    })),
+    order: meta.order ?? 99,
+  }))
+  .sort((left, right) => left.order - right.order || left.name.localeCompare(right.name));
+
+const groups = [...new Set(agents.map((agent) => agent.group))].map((id) => ({
+  id,
+  name: groupNames[id] ?? id,
+}));
+
+/* Typed as the schema the pages and the explorer already consume, so this module
+   is a drop-in for the generated catalog.json it replaces. schema_version is
+   asserted rather than read from the lock file: it versions this site-facing
+   shape, not the installer contract the lock file carries. */
+export const catalog: SiteCatalogV2 = { schema_version: 2, groups, agents, providers };
diff --git a/site/src/lib/content.ts b/site/src/lib/content.ts
index 87d0a37b..9cbeec12 100644
--- a/site/src/lib/content.ts
+++ b/site/src/lib/content.ts
@@ -1,40 +1,13 @@
-export const agentDescriptions: Record<string, string> = {
-  codex: "OpenAI 的终端编码 Agent，OneAgent 管理 Responses 协议配置。",
-  "claude-code": "Anthropic 的终端编码 Agent，使用 Anthropic-compatible 配置。",
-  cursor: "AI 编辑器；OneAgent 只提供官方安装与登录引导，不写入私有配置。",
-  opencode: "开源终端编码 Agent，使用 OpenAI-compatible 协议。",
-  openclaw: "多渠道 Agent 网关；按官方流程安装、onboard 与管理服务。",
-  hermes: "自我成长型 Agent 框架；模型与运行配置由官方工具管理。",
-  "gemini-cli": "Google 官方 CLI；使用 Google 登录、Gemini API Key 或 Vertex AI。",
-  "kilo-cli": "多模型命令行 Agent，OneAgent 可管理安装与 OpenAI-compatible 配置。",
-  aider: "结对编程式仓库编辑 Agent，模型在启动命令中明确选择。",
-  kiro: "官方账号型开发 Agent；使用官方登录与配置流程。",
-  cline: "IDE 扩展；在扩展界面选择兼容 Provider。",
-  continue: "IDE 扩展；在 Continue 配置中添加兼容模型。",
-  "qwen-code": "Qwen 的编码工具；按官方文档完成安装和 Provider 配置。",
-  "kilo-vscode": "Kilo Code 的 VS Code 扩展；由扩展界面管理 Provider。",
-};
-
-export const groupLabels: Record<string, string> = {
-  auto: "OneAgent 可管理",
-  gateway: "Gateway Agent",
-  platform: "官方账号 Agent",
-  ide: "IDE 扩展",
-};
-
+/**
+ * Language-neutral catalogue labels: these are proper nouns, identical in every
+ * locale. Translated labels live in src/i18n/catalog.ts.
+ */
 export const protocolLabels: Record<string, string> = {
   openai: "OpenAI Chat Completions",
   anthropic: "Anthropic Messages",
   responses: "OpenAI Responses",
 };
 
-export const protocolStatusLabels: Record<string, string> = {
-  "implementation-supported": "实现已接入",
-  "release-candidate-required": "需 Release Candidate 实证",
-  verified: "已验证",
-  unsupported: "不支持",
-};
-
 export const platformLabels: Record<string, string> = {
   macos: "macOS",
   windows: "Windows",
diff --git a/site/src/lib/demo-environment.ts b/site/src/lib/demo-environment.ts
new file mode 100644
index 00000000..738950eb
--- /dev/null
+++ b/site/src/lib/demo-environment.ts
@@ -0,0 +1,54 @@
+import type { SiteAgent, SiteCatalogV2 } from "./explorer";
+
+export type DemoStatus = "ready" | "attention" | "guide-only" | "not-installed";
+export type DemoVersion = "locked" | "behind" | null;
+
+export interface DemoAgentState {
+  installed: boolean;
+  configured: boolean;
+  status: DemoStatus;
+  version: DemoVersion;
+  hasBackup: boolean;
+}
+
+export const DEMO_AGENT_STATES: Readonly<Record<string, DemoAgentState>> = {
+  codex: { installed: true, configured: false, status: "attention", version: "behind", hasBackup: true },
+  "claude-code": { installed: true, configured: true, status: "ready", version: "locked", hasBackup: true },
+  cursor: { installed: true, configured: false, status: "guide-only", version: null, hasBackup: false },
+  opencode: { installed: false, configured: false, status: "not-installed", version: null, hasBackup: false },
+};
+
+/* The product discovers models from the endpoint's own /v1/models. These lists
+   stand in for one such response. The first entry of each is the provider's real
+   fallback_probe_model from oneagent/catalog.py — including the fact that the
+   same DeepSeek build is published under a different id per provider, which is
+   why the product cannot share one constant. */
+export const DEMO_MODELS: Readonly<Record<string, readonly string[]>> = {
+  ppio: ["deepseek/deepseek-v3", "qwen/qwen3-coder-480b", "moonshotai/kimi-k2"],
+  novita: ["deepseek/deepseek_v3", "qwen/qwen3-235b-a22b", "meta-llama/llama-4-maverick"],
+};
+
+/* A custom endpoint has no published catalog, so the demo shows the product's
+   documented recovery instead of inventing a list: type the id by hand. */
+export const DEMO_CUSTOM_MODEL_HINT = "deepseek/deepseek-v3";
+
+export function demoModelsFor(providerId: string | null): readonly string[] {
+  return (providerId && DEMO_MODELS[providerId]) || [];
+}
+
+export function missingDemoAgentIds(
+  catalog: SiteCatalogV2,
+  states: Readonly<Record<string, DemoAgentState>> = DEMO_AGENT_STATES,
+): string[] {
+  const ids = new Set(catalog.agents.map((agent) => agent.id));
+  return Object.keys(states).filter((id) => !ids.has(id)).sort();
+}
+
+export function demoStateFor(agent: SiteAgent): DemoAgentState {
+  const explicit = DEMO_AGENT_STATES[agent.id];
+  if (explicit) return explicit;
+  if (agent.support.officialInstallGuide) {
+    return { installed: false, configured: false, status: "guide-only", version: null, hasBackup: false };
+  }
+  return { installed: false, configured: false, status: "not-installed", version: null, hasBackup: false };
+}
diff --git a/site/src/lib/downloads.test.ts b/site/src/lib/downloads.test.ts
index 70c51e1d..cd5d38bd 100644
--- a/site/src/lib/downloads.test.ts
+++ b/site/src/lib/downloads.test.ts
@@ -1,11 +1,6 @@
 import { describe, expect, it } from "vitest";
-import {
-  detectTargetFromUserAgent,
-  formatBytes,
-  getRecommendedTarget,
-  supportLabels,
-  type ReleaseChannel,
-} from "./downloads";
+import { detectTargetFromUserAgent, formatBytes, supportLabels } from "./downloads";
+import { recommendedTargetIn, type ReleaseChannel } from "./release-channel";
 
 const channel: ReleaseChannel = {
   channel: "technical-preview-unsigned",
@@ -75,11 +70,11 @@ describe("download targeting", () => {
   });
 
   it("returns an unavailable target when it is the user's platform", () => {
-    expect(getRecommendedTarget(channel, { platform: "windows", arch: "x64" })?.id).toBe("windows-x64");
+    expect(recommendedTargetIn(channel, { platform: "windows", arch: "x64" })?.id).toBe("windows-x64");
   });
 
   it("falls back to the available artifact for an unknown browser", () => {
-    expect(getRecommendedTarget(channel, null)?.id).toBe("macos-arm64");
+    expect(recommendedTargetIn(channel, null)?.id).toBe("macos-arm64");
   });
 
   it("formats download size without pretending to be exact decimal storage", () => {
diff --git a/site/src/lib/downloads.ts b/site/src/lib/downloads.ts
index 5199ed4c..e2f92c73 100644
--- a/site/src/lib/downloads.ts
+++ b/site/src/lib/downloads.ts
@@ -1,47 +1,31 @@
-export type TargetStatus = "available" | "verification-pending" | "planned" | "withdrawn";
-
-export interface DownloadLink {
+export interface ReleaseTarget {
   id: string;
-  label: string;
-  kind: "official" | "mirror";
-  url: string;
-  primary: boolean;
-}
-
-export interface ReleaseArtifact {
+  platform: "macos" | "windows" | "linux";
+  platformLabel: string;
+  arch: "arm64" | "x64";
+  archLabel: string;
   file: string;
-  sha256: string;
   bytes: number;
-  kind: "binary" | "source";
-  downloads: DownloadLink[];
+  sha256: string | null;
+  downloadUrl: string;
+  checksumUrl: string | null;
 }
 
-export interface ReleaseTarget {
-  id: string;
-  platform: string;
-  platformLabel: string;
-  arch: string;
-  archLabel: string;
-  status: TargetStatus;
-  verification: {
-    native_build: boolean;
-    cleanroom: "verified" | "not-recorded" | "failed";
-    evidence: string | null;
-  };
-  python: string | null;
-  built_at: string | null;
-  agent_versions: Record<string, string>;
-  artifacts: ReleaseArtifact[];
+export interface GitHubReleaseAsset {
+  name: string;
+  size: number;
+  digest?: string | null;
+  browser_download_url: string;
 }
 
-export interface ReleaseChannel {
-  channel: string;
-  label: string;
+export interface GitHubRelease {
+  name: string | null;
+  tag_name: string;
+  html_url: string;
   published_at: string | null;
-  version: string | null;
-  unsigned: boolean;
-  status: "available" | "unavailable";
-  targets: ReleaseTarget[];
+  prerelease: boolean;
+  draft: boolean;
+  assets: GitHubReleaseAsset[];
 }
 
 export interface DetectedTarget {
@@ -55,6 +39,59 @@ export interface AgentSupport {
   managedConfig: boolean;
 }
 
+const repository = process.env.GITHUB_REPOSITORY || "MaimoryLab/OneAgent";
+const releasesUrl = `https://api.github.com/repos/${repository}/releases?per_page=20`;
+export const releasesPageUrl = `https://github.com/${repository}/releases`;
+let releasesRequest: Promise<GitHubRelease[]> | undefined;
+
+export function getPublishedReleases(): Promise<GitHubRelease[]> {
+  releasesRequest ??= fetch(releasesUrl, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      ...(process.env.GITHUB_TOKEN ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } : {}),
+    },
+  }).then(async (response) => {
+    if (response.status === 404 && !process.env.GITHUB_TOKEN) return [];
+    if (!response.ok) throw new Error(`GitHub Releases request failed: ${response.status} ${response.statusText}`);
+    const releases = await response.json();
+    if (!Array.isArray(releases)) throw new Error("GitHub Releases response must be an array");
+    return (releases as GitHubRelease[]).filter((release) => !release.draft);
+  });
+  return releasesRequest;
+}
+
+export async function getLatestRelease(): Promise<GitHubRelease | null> {
+  return (await getPublishedReleases())[0] ?? null;
+}
+
+const platformLabels = { macos: "macOS", windows: "Windows", linux: "Linux" } as const;
+const archLabels = { arm64: "Apple silicon / ARM64", x64: "Intel / AMD 64-bit" } as const;
+const binarySuffixes = [".zip", ".tar.gz", ".dmg", ".msi", ".exe", ".appimage"];
+
+export function releaseTargets(release: GitHubRelease): ReleaseTarget[] {
+  return release.assets.flatMap((asset) => {
+    const match = asset.name.toLowerCase().match(/-(macos|windows|linux)-(arm64|x64)(?:\.[a-z0-9.]+)$/);
+    if (!match || !binarySuffixes.some((suffix) => asset.name.toLowerCase().endsWith(suffix))) return [];
+    const platform = match[1] as ReleaseTarget["platform"];
+    const arch = match[2] as ReleaseTarget["arch"];
+    const digest = asset.digest?.match(/^sha256:([a-f0-9]{64})$/i)?.[1].toLowerCase() ?? null;
+    const checksum = release.assets.find((candidate) => candidate.name === `SHA256SUMS-${platform}-${arch}.txt`);
+    return [{
+      id: `${platform}-${arch}`,
+      platform,
+      platformLabel: platformLabels[platform],
+      arch,
+      archLabel: archLabels[arch],
+      file: asset.name,
+      bytes: asset.size,
+      sha256: digest,
+      downloadUrl: asset.browser_download_url,
+      checksumUrl: checksum?.browser_download_url ?? null,
+    }];
+  });
+}
+
 export function detectTargetFromUserAgent(userAgent: string): DetectedTarget | null {
   const normalized = userAgent.toLowerCase();
   if (/iphone|ipad|android/.test(normalized)) return null;
@@ -73,28 +110,16 @@ export function detectTargetFromUserAgent(userAgent: string): DetectedTarget | n
   return null;
 }
 
-export function getRecommendedTarget(channel: ReleaseChannel, detected: DetectedTarget | null): ReleaseTarget | null {
+export function getRecommendedTarget(targets: ReleaseTarget[], detected: DetectedTarget | null): ReleaseTarget | null {
   if (detected) {
     const exact = detected.arch
-      ? channel.targets.find((target) => target.platform === detected.platform && target.arch === detected.arch)
+      ? targets.find((target) => target.platform === detected.platform && target.arch === detected.arch)
       : null;
     if (exact) return exact;
-    const samePlatform = channel.targets.find(
-      (target) => target.platform === detected.platform && target.status === "available",
-    );
+    const samePlatform = targets.find((target) => target.platform === detected.platform);
     if (samePlatform) return samePlatform;
-    const anySamePlatform = channel.targets.find((target) => target.platform === detected.platform);
-    if (anySamePlatform) return anySamePlatform;
   }
-  return channel.targets.find((target) => target.status === "available") ?? channel.targets[0] ?? null;
-}
-
-export function binaryArtifact(target: ReleaseTarget): ReleaseArtifact | null {
-  return target.artifacts.find((artifact) => artifact.kind === "binary") ?? null;
-}
-
-export function primaryDownload(artifact: ReleaseArtifact): DownloadLink | null {
-  return artifact.downloads.find((download) => download.primary) ?? artifact.downloads[0] ?? null;
+  return targets[0] ?? null;
 }
 
 export function formatBytes(bytes: number): string {
diff --git a/site/src/lib/explorer.test.ts b/site/src/lib/explorer.test.ts
new file mode 100644
index 00000000..8e2a9956
--- /dev/null
+++ b/site/src/lib/explorer.test.ts
@@ -0,0 +1,128 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compatibilityFor,
+  parseExplorerSearch,
+  recommendedCombination,
+  serializeExplorerSearch,
+  type SiteCatalogV2,
+} from "./explorer";
+
+const catalog: SiteCatalogV2 = {
+  schema_version: 2,
+  groups: [{ id: "auto", name: "Auto" }, { id: "ide", name: "IDE" }],
+  agents: [
+    {
+      id: "responses-agent",
+      name: "Responses Agent",
+      group: "auto",
+      rank: 1,
+      command: "responses-agent",
+      configPath: ".responses/config.json",
+      platforms: ["macos"],
+      lockedVersion: "1.0.0",
+      source: null,
+      license: null,
+      licenseUrl: null,
+      guide: null,
+      protocol: "responses",
+      support: { managedInstall: true, officialInstallGuide: false, managedConfig: true },
+    },
+    {
+      id: "anthropic-agent",
+      name: "Anthropic Agent",
+      group: "auto",
+      rank: 2,
+      command: "anthropic-agent",
+      configPath: ".anthropic/config.json",
+      platforms: ["macos", "linux"],
+      lockedVersion: "2.0.0",
+      source: null,
+      license: null,
+      licenseUrl: null,
+      guide: null,
+      protocol: "anthropic",
+      support: { managedInstall: true, officialInstallGuide: false, managedConfig: true },
+    },
+    {
+      id: "guided-agent",
+      name: "Guided Agent",
+      group: "ide",
+      rank: 3,
+      command: null,
+      configPath: null,
+      platforms: ["windows"],
+      lockedVersion: null,
+      source: null,
+      license: null,
+      licenseUrl: null,
+      guide: "Use the official account flow.",
+      protocol: null,
+      support: { managedInstall: false, officialInstallGuide: true, managedConfig: false },
+    },
+  ],
+  providers: [
+    {
+      id: "first",
+      name: "First Provider",
+      home: "https://first.example/",
+      relationship: "none",
+      disclosure: "",
+      referralUrl: "",
+      order: 1,
+      protocols: [
+        { id: "responses", status: "release-candidate-required" },
+        { id: "anthropic", status: "implementation-supported" },
+      ],
+    },
+    {
+      id: "verified",
+      name: "Verified Provider",
+      home: "https://verified.example/",
+      relationship: "none",
+      disclosure: "",
+      referralUrl: "",
+      order: 2,
+      protocols: [{ id: "anthropic", status: "verified" }],
+    },
+  ],
+};
+
+describe("provider compatibility", () => {
+  it("maps provider registry statuses without upgrading preview support to ready", () => {
+    expect(compatibilityFor(catalog.agents[0], catalog.providers[0])).toBe("preview-gate");
+    expect(compatibilityFor(catalog.agents[1], catalog.providers[0])).toBe("supported");
+    expect(compatibilityFor(catalog.agents[1], catalog.providers[1])).toBe("verified");
+    expect(compatibilityFor(catalog.agents[2], catalog.providers[0])).toBe("unsupported");
+  });
+
+  it("recommends the first ranked combination that may truthfully reach ready", () => {
+    expect(recommendedCombination(catalog)).toEqual({ agentId: "anthropic-agent", providerId: "first" });
+  });
+});
+
+describe("Explorer URL state", () => {
+  it("parses a compatible, shareable selection", () => {
+    expect(
+      parseExplorerSearch(
+        "?agent=anthropic-agent&provider=first&platform=linux&protocol=anthropic",
+        catalog,
+      ),
+    ).toEqual({ agent: "anthropic-agent", provider: "first", platform: "linux", protocol: "anthropic" });
+  });
+
+  it("drops unknown values and combinations that contradict the selected agent", () => {
+    expect(
+      parseExplorerSearch(
+        "?agent=responses-agent&provider=verified&platform=windows&protocol=anthropic",
+        catalog,
+      ),
+    ).toEqual({ agent: "responses-agent", provider: null, platform: null, protocol: null });
+  });
+
+  it("serializes only active values in a stable order", () => {
+    expect(
+      serializeExplorerSearch({ agent: "anthropic-agent", provider: "first", platform: null, protocol: "anthropic" }),
+    ).toBe("agent=anthropic-agent&provider=first&protocol=anthropic");
+  });
+});
diff --git a/site/src/lib/explorer.ts b/site/src/lib/explorer.ts
new file mode 100644
index 00000000..6df02ae2
--- /dev/null
+++ b/site/src/lib/explorer.ts
@@ -0,0 +1,155 @@
+export const platformIds = ["macos", "linux", "windows"] as const;
+export type PlatformId = (typeof platformIds)[number];
+
+export const protocolIds = ["openai", "anthropic", "responses"] as const;
+export type ProtocolId = (typeof protocolIds)[number];
+
+export type ProviderProtocolStatus =
+  | "implementation-supported"
+  | "release-candidate-required"
+  | "verified"
+  | "unsupported";
+
+export interface SiteAgentSupport {
+  managedInstall: boolean;
+  officialInstallGuide: boolean;
+  managedConfig: boolean;
+}
+
+export interface SiteAgent {
+  id: string;
+  name: string;
+  group: string;
+  rank: number;
+  command: string | null;
+  configPath: string | null;
+  platforms: PlatformId[];
+  lockedVersion: string | null;
+  source: string | null;
+  license: string | null;
+  licenseUrl: string | null;
+  guide: string | null;
+  protocol: ProtocolId | null;
+  support: SiteAgentSupport;
+}
+
+export interface SiteProviderProtocol {
+  id: ProtocolId;
+  status: ProviderProtocolStatus;
+}
+
+export interface SiteProvider {
+  id: string;
+  name: string;
+  home: string;
+  relationship: "none" | "referral" | "sponsor";
+  disclosure: string;
+  referralUrl: string;
+  protocols: SiteProviderProtocol[];
+  order: number;
+}
+
+export interface SiteAgentGroup {
+  id: string;
+  name: string;
+}
+
+export interface SiteCatalogV2 {
+  schema_version: 2;
+  groups: SiteAgentGroup[];
+  agents: SiteAgent[];
+  providers: SiteProvider[];
+}
+
+export type Compatibility = "verified" | "supported" | "preview-gate" | "unsupported";
+
+export interface RecommendedCombination {
+  agentId: string;
+  providerId: string;
+}
+
+export interface ExplorerSearchState {
+  agent: string | null;
+  provider: string | null;
+  platform: PlatformId | null;
+  protocol: ProtocolId | null;
+}
+
+export function protocolStatusFor(provider: SiteProvider, protocol: ProtocolId | null): ProviderProtocolStatus {
+  if (!protocol) return "unsupported";
+  return provider.protocols.find((entry) => entry.id === protocol)?.status ?? "unsupported";
+}
+
+export function compatibilityFor(agent: SiteAgent, provider: SiteProvider): Compatibility {
+  switch (protocolStatusFor(provider, agent.protocol)) {
+    case "verified":
+      return "verified";
+    case "implementation-supported":
+      return "supported";
+    case "release-candidate-required":
+      return "preview-gate";
+    default:
+      return "unsupported";
+  }
+}
+
+export function recommendedCombination(catalog: SiteCatalogV2): RecommendedCombination | null {
+  const agents = [...catalog.agents].sort((left, right) => left.rank - right.rank || left.id.localeCompare(right.id));
+  const providers = [...catalog.providers].sort(
+    (left, right) => left.order - right.order || left.name.localeCompare(right.name),
+  );
+
+  for (const agent of agents) {
+    if (!agent.support.managedConfig || !agent.protocol) continue;
+    const provider = providers.find((candidate) => {
+      const compatibility = compatibilityFor(agent, candidate);
+      return compatibility === "supported" || compatibility === "verified";
+    });
+    if (provider) return { agentId: agent.id, providerId: provider.id };
+  }
+  return null;
+}
+
+function isPlatform(value: string | null): value is PlatformId {
+  return Boolean(value && platformIds.includes(value as PlatformId));
+}
+
+function isProtocol(value: string | null): value is ProtocolId {
+  return Boolean(value && protocolIds.includes(value as ProtocolId));
+}
+
+export function parseExplorerSearch(search: string, catalog: SiteCatalogV2): ExplorerSearchState {
+  const params = new URLSearchParams(search.startsWith("?") ? search.slice(1) : search);
+  const selectedAgent = catalog.agents.find((agent) => agent.id === params.get("agent")) ?? null;
+  let selectedProvider = catalog.providers.find((provider) => provider.id === params.get("provider")) ?? null;
+  const requestedPlatform = params.get("platform");
+  const requestedProtocol = params.get("protocol");
+
+  let platform = isPlatform(requestedPlatform) ? requestedPlatform : null;
+  let protocol = isProtocol(requestedProtocol) ? requestedProtocol : null;
+
+  if (selectedAgent) {
+    if (platform && !selectedAgent.platforms.includes(platform)) platform = null;
+    if (protocol && selectedAgent.protocol !== protocol) protocol = null;
+    if (selectedProvider && compatibilityFor(selectedAgent, selectedProvider) === "unsupported") selectedProvider = null;
+  }
+  if (selectedProvider && protocol && protocolStatusFor(selectedProvider, protocol) === "unsupported") {
+    selectedProvider = null;
+  }
+
+  return {
+    agent: selectedAgent?.id ?? null,
+    provider: selectedProvider?.id ?? null,
+    platform,
+    protocol,
+  };
+}
+
+export function serializeExplorerSearch(state: ExplorerSearchState): string {
+  const params = new URLSearchParams();
+  if (state.agent) params.set("agent", state.agent);
+  if (state.provider) params.set("provider", state.provider);
+  if (state.platform) params.set("platform", state.platform);
+  if (state.protocol) params.set("protocol", state.protocol);
+  return params.toString();
+}
diff --git a/site/src/lib/release-channel.ts b/site/src/lib/release-channel.ts
new file mode 100644
index 00000000..d0a1fe37
--- /dev/null
+++ b/site/src/lib/release-channel.ts
@@ -0,0 +1,174 @@
+/**
+ * Adapts GitHub Releases into the channel shape the pages render.
+ *
+ * The pages were written against a locally generated release index that carried
+ * per-target build provenance: which Python built it, whether the build was
+ * native, whether a cleanroom run passed. GitHub Releases carries none of that —
+ * it knows an asset's name, size and digest, and nothing about how it was made.
+ *
+ * So this module maps what the API does return and reports the rest as unknown
+ * rather than filling it in. `native_build: false` and `cleanroom:
+ * "not-recorded"` are the honest readings of "the release feed cannot tell us",
+ * and the pages already render that as an absence of evidence instead of a
+ * claim. Inventing a `true` here would put a verification badge on the site that
+ * nothing checked.
+ */
+import {
+  type DetectedTarget,
+  type GitHubRelease,
+  type ReleaseTarget as AssetTarget,
+  getLatestRelease,
+  releaseTargets,
+} from "./downloads";
+
+export type { DetectedTarget };
+
+export type TargetStatus = "available" | "verification-pending" | "planned" | "withdrawn";
+
+export interface DownloadLink {
+  id: string;
+  label: string;
+  kind: "official" | "mirror";
+  url: string;
+  primary: boolean;
+}
+
+export interface ReleaseArtifact {
+  file: string;
+  sha256: string;
+  bytes: number;
+  kind: "binary" | "source";
+  downloads: DownloadLink[];
+}
+
+export interface ReleaseTarget {
+  id: string;
+  platform: string;
+  platformLabel: string;
+  arch: string;
+  archLabel: string;
+  status: TargetStatus;
+  verification: {
+    native_build: boolean;
+    cleanroom: "verified" | "not-recorded" | "failed";
+    evidence: string | null;
+  };
+  python: string | null;
+  built_at: string | null;
+  agent_versions: Record<string, string>;
+  artifacts: ReleaseArtifact[];
+}
+
+export interface ReleaseChannel {
+  channel: string;
+  label: string;
+  published_at: string | null;
+  version: string | null;
+  unsigned: boolean;
+  status: "available" | "unavailable";
+  targets: ReleaseTarget[];
+}
+
+/* Every platform/arch OneAgent intends to ship, in the order the download page
+   lists them. Targets with no asset in the release still appear, as `planned` —
+   a reader comparing platforms should see that Windows exists and is not ready
+   yet, rather than find it missing and wonder. */
+const plannedTargets: Array<{ id: string; platform: string; platformLabel: string; arch: string; archLabel: string }> = [
+  { id: "macos-arm64", platform: "macos", platformLabel: "macOS", arch: "arm64", archLabel: "Apple silicon / ARM64" },
+  { id: "macos-x64", platform: "macos", platformLabel: "macOS", arch: "x64", archLabel: "Intel / AMD 64-bit" },
+  { id: "windows-x64", platform: "windows", platformLabel: "Windows", arch: "x64", archLabel: "Intel / AMD 64-bit" },
+  { id: "linux-x64", platform: "linux", platformLabel: "Linux", arch: "x64", archLabel: "Intel / AMD 64-bit" },
+];
+
+export const previewChannelId = "technical-preview-unsigned";
+
+/* The tag carries the channel. A prerelease tag, or one saying so in its name,
+   is the unsigned technical preview; anything else is a signed stable build.
+   Read from the release rather than hardcoded so the site follows the tag
+   instead of needing an edit on the day Stable ships. */
+function channelOf(release: GitHubRelease): { channel: string; label: string; unsigned: boolean } {
+  const preview = release.prerelease || /preview|unsigned|dev|rc/i.test(release.tag_name);
+  return preview
+    ? { channel: previewChannelId, label: "未签名技术预览版", unsigned: true }
+    : { channel: "stable", label: "稳定版", unsigned: false };
+}
+
+function artifactFor(asset: AssetTarget): ReleaseArtifact[] {
+  /* A missing digest means the asset predates GitHub's per-asset digests. The
+     checksum file is still linked, so a reader can verify by hand — but the page
+     must not print a checksum that was never published. */
+  if (!asset.sha256) return [];
+  return [{
+    file: asset.file,
+    sha256: asset.sha256,
+    bytes: asset.bytes,
+    kind: "binary",
+    downloads: [{ id: "github", label: "GitHub Releases", kind: "official", url: asset.downloadUrl, primary: true }],
+  }];
+}
+
+/**
+ * Builds the channel the pages render from the newest published release.
+ *
+ * Returns null when the release feed is empty or unreachable, which is the state
+ * a fresh fork is in. Callers render the "not published yet" copy for null
+ * rather than failing the build, because a site that cannot be built without a
+ * network round trip cannot be built in CI.
+ */
+export async function getPreviewChannel(): Promise<ReleaseChannel | null> {
+  const release = await getLatestRelease();
+  if (!release) return null;
+  const assets = releaseTargets(release);
+  const { channel, label, unsigned } = channelOf(release);
+  const targets: ReleaseTarget[] = plannedTargets.map((planned) => {
+    const asset = assets.find((candidate) => candidate.id === planned.id);
+    const artifacts = asset ? artifactFor(asset) : [];
+    return {
+      ...planned,
+      /* An asset whose digest never got published is `verification-pending`, not
+         `available`: the download page's whole claim is that you can check what
+         you downloaded, and without a checksum you cannot. */
+      status: !asset ? "planned" : artifacts.length > 0 ? "available" : "verification-pending",
+      verification: { native_build: false, cleanroom: "not-recorded", evidence: "security/#release-evidence" },
+      python: null,
+      built_at: release.published_at,
+      agent_versions: {},
+      artifacts,
+    };
+  });
+  return {
+    channel,
+    label,
+    published_at: release.published_at,
+    version: release.tag_name.replace(/^v/, ""),
+    unsigned,
+    status: targets.some((target) => target.status === "available") ? "available" : "unavailable",
+    targets,
+  };
+}
+/* Named for the channel it takes, because downloads.ts exports a
+   getRecommendedTarget over a bare asset list. Same intent, different input, and
+   one importing both would otherwise get whichever the bundler resolved last. */
+export function recommendedTargetIn(channel: ReleaseChannel, detected: DetectedTarget | null): ReleaseTarget | null {
+  if (detected) {
+    const exact = detected.arch
+      ? channel.targets.find((target) => target.platform === detected.platform && target.arch === detected.arch)
+      : null;
+    if (exact) return exact;
+    const samePlatform = channel.targets.find(
+      (target) => target.platform === detected.platform && target.status === "available",
+    );
+    if (samePlatform) return samePlatform;
+    const anySamePlatform = channel.targets.find((target) => target.platform === detected.platform);
+    if (anySamePlatform) return anySamePlatform;
+  }
+  return channel.targets.find((target) => target.status === "available") ?? channel.targets[0] ?? null;
+}
+
+export function binaryArtifact(target: ReleaseTarget): ReleaseArtifact | null {
+  return target.artifacts.find((artifact) => artifact.kind === "binary") ?? null;
+}
+
+export function primaryDownload(artifact: ReleaseArtifact): DownloadLink | null {
+  return artifact.downloads.find((download) => download.primary) ?? artifact.downloads[0] ?? null;
+}
diff --git a/site/src/pages/agents/[id].astro b/site/src/pages/agents/[id].astro
index 2ab9ef56..7a37fb44 100644
--- a/site/src/pages/agents/[id].astro
+++ b/site/src/pages/agents/[id].astro
@@ -1,15 +1,18 @@
 ---
 import BaseLayout from "../../layouts/BaseLayout.astro";
 import AgentMark from "../../components/AgentMark.astro";
-import catalogData from "../../generated/catalog.json";
-import { agentDescriptions, groupLabels, platformLabels, protocolLabels } from "../../lib/content";
+import { catalog } from "../../lib/catalog";
+import { platformLabels, protocolLabels } from "../../lib/content";
+import { localeFromPath } from "../../i18n";
+import { useCatalogLabels } from "../../i18n/catalog";
 import { supportLabels } from "../../lib/downloads";
 
 export function getStaticPaths() {
-  return (catalogData as any).agents.map((agent: any) => ({ params: { id: agent.id }, props: { agent } }));
+  return catalog.agents.map((agent: any) => ({ params: { id: agent.id }, props: { agent } }));
 }
 const { agent } = Astro.props as any;
 const labels = supportLabels(agent.support);
+const { agentDescriptions, groupLabels } = useCatalogLabels(localeFromPath(Astro.url.pathname));
 ---
 <BaseLayout title={`${agent.name} — OneAgent Agent 兼容目录`} description={agentDescriptions[agent.id] ?? `${agent.name} 在 OneAgent 中的安装、配置和协议支持状态。`}>
   <header class="page-hero">
diff --git a/site/src/pages/agents/index.astro b/site/src/pages/agents/index.astro
index d2b5885f..1be9f6ef 100644
--- a/site/src/pages/agents/index.astro
+++ b/site/src/pages/agents/index.astro
@@ -1,9 +1,11 @@
 ---
 import BaseLayout from "../../layouts/BaseLayout.astro";
 import AgentMark from "../../components/AgentMark.astro";
-import catalogData from "../../generated/catalog.json";
-import { agentDescriptions, groupLabels, protocolLabels } from "../../lib/content";
-const catalog = catalogData as any;
+import { catalog } from "../../lib/catalog";
+import { protocolLabels } from "../../lib/content";
+import { localeFromPath } from "../../i18n";
+import { useCatalogLabels } from "../../i18n/catalog";
+const { agentDescriptions, groupLabels, agentFallbackDescription } = useCatalogLabels(localeFromPath(Astro.url.pathname));
 ---
 <BaseLayout title="Agent 兼容目录 — OneAgent" description="按安装、配置、协议和平台分别查看 OneAgent 对各 Agent 的真实支持范围。">
   <header class="page-hero">
@@ -15,12 +17,12 @@ const catalog = catalogData as any;
   <section class="section-compact">
     <div class="shell">
       <div class="notice notice-info" style="margin-bottom:34px"><span class="notice-mark">i</span><div><strong>guide-only 仍然是有效流程</strong><p>它表示 OneAgent 返回官方安装或配置指引并在 Review 中保留结果，而不是一个不可选择的禁用项。</p></div></div>
-      <div class="agent-list">
+      <div class="agent-list reveal">
         {catalog.agents.map((agent: any) => (
           <a class="agent-row" href={`agents/${agent.id}/`}>
             <AgentMark id={agent.id} name={agent.name} />
             <div><strong>{agent.name}</strong><span class="agent-meta">{groupLabels[agent.group] ?? agent.group}{agent.lockedVersion ? ` · ${agent.lockedVersion}` : ""}</span></div>
-            <span class="agent-meta">{agentDescriptions[agent.id] ?? "按项目公开能力提供安装或配置支持。"}</span>
+            <span class="agent-meta">{agentDescriptions[agent.id] ?? agentFallbackDescription}</span>
             <div class="agent-status">
               {agent.support.managedInstall ? <span class="chip chip-green">管理安装</span> : <span class="chip">官方引导</span>}
               {agent.support.managedConfig ? <span class="chip chip-blue">管理配置</span> : <span class="chip">官方配置</span>}
diff --git a/site/src/pages/changelog/index.astro b/site/src/pages/changelog/index.astro
index 9b064b6b..2b5cc8dd 100644
--- a/site/src/pages/changelog/index.astro
+++ b/site/src/pages/changelog/index.astro
@@ -9,7 +9,7 @@ import BaseLayout from "../../layouts/BaseLayout.astro";
     </div>
   </header>
   <section class="section-compact">
-    <div class="wide-narrow timeline">
+    <div class="wide-narrow timeline reveal">
       <article class="timeline-item"><div class="timeline-date">2026-07-28<br />0.2.0-dev</div><div><span class="chip chip-blue">开发中</span><h2>可信分发站与发行事实层</h2><ul><li>新增由平台 manifest、SHA256SUMS 和渠道配置生成的公开发行索引。</li><li>macOS arm64 产物完成精确 SHA-256 对应的原生 cleanroom 复核。</li><li>新增独立公开网站，不改变本地 Launcher 打包与运行方式。</li></ul></div></article>
       <article class="timeline-item"><div class="timeline-date">2026-07-28<br />af14f3e</div><div><h2>选择页排序与总览一致</h2><ul><li>按 rank 划分首屏 Agent，避免使用 group 代替用户认知排序。</li><li>guide-only Agent 继续可选择并在 Review 中返回引导结果。</li></ul></div></article>
       <article class="timeline-item"><div class="timeline-date">2026-07-27<br />1cf37bf</div><div><h2>记录 CC Switch 表单研究的正确边界</h2><ul><li>确认共享编排器与专属字段区块并存，而不是每个 Agent 完全复制一套表单。</li><li>暂缓按底层配置格式拆分 OneAgent 表单，只响应真实用户选择。</li></ul></div></article>
diff --git a/site/src/pages/downloads/index.astro b/site/src/pages/downloads/index.astro
index d688e692..7ba3fbb4 100644
--- a/site/src/pages/downloads/index.astro
+++ b/site/src/pages/downloads/index.astro
@@ -8,11 +8,11 @@ import DownloadSelector from "../../components/DownloadSelector.astro";
       <div>
         <nav class="breadcrumb" aria-label="面包屑"><a href="">首页</a> / 下载</nav>
         <p class="eyebrow">Download center</p>
-        <h1 class="page-title">下载之前，先看清它是什么。</h1>
+        <h1 class="page-title">选好平台，直接开始。</h1>
       </div>
       <div class="page-hero-aside">
         <strong>无需 OneAgent 账号</strong>
-        选择与你设备匹配的产物，核对版本、签名状态与 SHA-256，再开始本地激活流程。
+        每个产物都带着版本、体积、构建日期与 SHA-256，下载前你就能核对清楚。
       </div>
     </div>
   </header>
@@ -22,11 +22,13 @@ import DownloadSelector from "../../components/DownloadSelector.astro";
   <section class="section section-muted">
     <div class="narrow prose">
       <p class="eyebrow">Integrity</p>
-      <h2 class="section-title">为什么下载页一定要显示 SHA-256？</h2>
-      <p>下载渠道只是镜像，不应该改变包体。对同一版本而言，官网、GitHub Release、网盘和企业云盘上的文件必须拥有完全相同的 SHA-256。渠道方不能追加推广文件、替换安装脚本或再次签名。</p>
-      <p>如果你计算出的值与页面不一致，请不要运行该文件，并通过支持页面报告下载地址、文件名和实际哈希。</p>
-      <h3>为什么当前不叫 Stable？</h3>
-      <p>当前技术预览包尚未完成 macOS Developer ID 公证或 Windows Authenticode。OneAgent 不通过降低系统安全策略来掩盖这项缺失；每个平台只有在签名、公证和原生验证门禁完成后，才会独立进入 Stable。</p>
+      <h2 class="section-title">页面上的 SHA-256 让你可以自己核对。</h2>
+      <p>下载渠道只是镜像。同一版本在官网、GitHub Release、网盘和企业云盘上的文件，SHA-256 完全一致。</p>
+      <p>渠道不追加推广文件，不替换安装脚本，不二次签名。</p>
+      <p>算出来的值和页面不一致？别运行它，把下载地址、文件名和实际哈希发到支持页面。</p>
+      <h3>当前是技术预览版</h3>
+      <p>macOS Developer ID 公证与 Windows Authenticode 还没完成，所以它不叫 Stable。签名、公证与原生验证门禁齐备后，每个平台各自进入 Stable。</p>
+      <p>在此期间，OneAgent 不提供降低系统安全策略的说明。</p>
     </div>
   </section>
 </BaseLayout>
diff --git a/site/src/pages/en/downloads/index.astro b/site/src/pages/en/downloads/index.astro
new file mode 100644
index 00000000..bd7e0d3b
--- /dev/null
+++ b/site/src/pages/en/downloads/index.astro
@@ -0,0 +1,38 @@
+---
+import BaseLayout from "../../../layouts/BaseLayout.astro";
+import DownloadSelector from "../../../components/DownloadSelector.astro";
+import { localePath } from "../../../i18n";
+---
+<BaseLayout
+  title="Download OneAgent — unsigned technical preview"
+  description="Download the OneAgent technical preview, published with a manifest, SHA-256 and native cleanroom evidence."
+>
+  <header class="page-hero">
+    <div class="shell page-hero-grid">
+      <div>
+        <nav class="breadcrumb" aria-label="Breadcrumb"><a href={localePath("en", "")}>Home</a> / Downloads</nav>
+        <p class="eyebrow">Download center</p>
+        <h1 class="page-title">Pick your platform and get started.</h1>
+      </div>
+      <div class="page-hero-aside">
+        <strong>No OneAgent account required</strong>
+        Every artifact carries its version, size, build date and SHA-256, so you can check it before you download.
+      </div>
+    </div>
+  </header>
+  <section class="section-compact">
+    <div class="shell"><DownloadSelector /></div>
+  </section>
+  <section class="section section-muted">
+    <div class="narrow prose">
+      <p class="eyebrow">Integrity</p>
+      <h2 class="section-title">The SHA-256 on this page is here so you can check it yourself.</h2>
+      <p>A distribution channel is a mirror. For a given version, the file on this site, on GitHub Releases, on a file host and on an internal drive all carry the identical SHA-256.</p>
+      <p>Channels do not append promotional files, swap the install script, or re-sign the build.</p>
+      <p>If the value you compute does not match the page, do not run the file. Send the download URL, the filename and the hash you actually got to the support page.</p>
+      <h3>This is a technical preview</h3>
+      <p>macOS Developer ID notarisation and Windows Authenticode are not done yet, so it is not called stable. Each platform enters stable on its own once signing, notarisation and native verification are complete.</p>
+      <p>Until then, OneAgent does not document ways around your operating system's security policy.</p>
+    </div>
+  </section>
+</BaseLayout>
diff --git a/site/src/pages/en/explore/index.astro b/site/src/pages/en/explore/index.astro
new file mode 100644
index 00000000..10e0f311
--- /dev/null
+++ b/site/src/pages/en/explore/index.astro
@@ -0,0 +1,21 @@
+---
+import CompatibilityExplorer from "../../../components/CompatibilityExplorer.astro";
+import BaseLayout from "../../../layouts/BaseLayout.astro";
+---
+<BaseLayout
+  title="AI development environment Explorer — OneAgent"
+  description="Explore OneAgent agent compatibility by platform, install path, configuration mode, protocol, provider and illustrative environment state."
+>
+  <section class="page-hero">
+    <div class="shell page-hero-grid">
+      <div>
+        <p class="eyebrow">Agent × Provider × Protocol</p>
+        <h1 class="page-title">Move from a compatibility catalog to an explicit activation path.</h1>
+      </div>
+      <p class="lede">Capabilities come from the real repository catalog; machine state is explicitly illustrative. Filter combinations, inspect details and preserve the selection in a shareable URL.</p>
+    </div>
+  </section>
+  <section class="section section-compact">
+    <div class="shell"><CompatibilityExplorer /></div>
+  </section>
+</BaseLayout>
diff --git a/site/src/pages/en/index.astro b/site/src/pages/en/index.astro
new file mode 100644
index 00000000..32223251
--- /dev/null
+++ b/site/src/pages/en/index.astro
@@ -0,0 +1,84 @@
+---
+import ActivationConsole from "../../components/ActivationConsole.astro";
+import AgentMark from "../../components/AgentMark.astro";
+import HeroParticles from "../../components/HeroParticles.astro";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import { catalog } from "../../lib/catalog";
+import { localePath } from "../../i18n";
+import { useCatalogLabels } from "../../i18n/catalog";
+import { protocolLabels } from "../../lib/content";
+import { getPreviewChannel } from "../../lib/release-channel";
+
+const preview = await getPreviewChannel();
+const available = preview?.targets.find((target) => target.status === "available");
+const primaryAgents = catalog.agents.slice(0, 6);
+const { agentDescriptions, groupLabels, agentFallbackDescription } = useCatalogLabels("en");
+const href = (path: string) => localePath("en", path);
+---
+<BaseLayout>
+  <section class="hero">
+    <HeroParticles />
+    <div class="shell hero-copy">
+      <div>
+        <p class="eyebrow">Local-first · Bring your own key</p>
+        <h1 class="display">One entry point,<br /><em>your whole AI dev environment.</em></h1>
+      </div>
+      <div class="hero-side">
+        <p class="lede">Move from agent to provider to protocol verification in one path. The demo below is live — real scanning, writes and backups happen in local OneAgent.</p>
+        <div class="hero-actions">
+          <button class="button button-primary" type="button" data-activation-trigger="activation-console" aria-controls="activation-console">Start activation demo</button>
+        </div>
+        <p class="hero-note">{preview?.version ? `${preview.version} · ` : ""}unsigned technical preview{available ? ` · currently ${available.platformLabel} ${available.archLabel}` : ""}</p>
+      </div>
+    </div>
+    <ActivationConsole />
+  </section>
+
+  <section class="section">
+    <div class="shell reveal">
+      <div class="section-heading">
+        <div><p class="eyebrow">One activation path</p><h2 class="section-title">Detect, connect and verify — with every step explained.</h2></div>
+        <p>Configuration, backups and credentials stay on your machine. The protocol an agent actually needs is verified before anything is written.</p>
+      </div>
+      <div class="steps">
+        <article class="step"><h3>Read the environment</h3><p>Installed, needs setup, official flow only — three states listed separately rather than flattened into one checkmark.</p></article>
+        <article class="step"><h3>Connect a provider</h3><p>Filter by the protocol an agent needs, or point it at your own endpoint. Every compatibility level is named.</p></article>
+        <article class="step"><h3>Verify and review</h3><p>Once verification passes: Ready state, the paths written, the backups taken, and the next command to run.</p></article>
+      </div>
+    </div>
+  </section>
+
+  <section class="section section-muted">
+    <div class="shell reveal">
+      <div class="section-heading">
+        <div><p class="eyebrow">Compatibility Explorer</p><h2 class="section-title">A real catalog, not a static compatibility poster.</h2></div>
+        <p>{catalog.agents.length} agents, {catalog.providers.length} public providers, and independent compatibility for OpenAI Responses, Anthropic Messages and Chat Completions.</p>
+      </div>
+      <div class="agent-list">
+        {primaryAgents.map((agent) => (
+          <a class="agent-row" href={href(`explore/?agent=${agent.id}`)}>
+            <AgentMark id={agent.id} name={agent.name} />
+            <div><strong>{agent.name}</strong><span class="agent-meta">{groupLabels[agent.group] ?? agent.group}</span></div>
+            <span class="agent-meta">{agentDescriptions[agent.id] ?? agentFallbackDescription}</span>
+            <div class="agent-status">
+              {agent.support.managedInstall ? <span class="chip chip-green">Managed install</span> : <span class="chip">Official guide</span>}
+              {agent.support.managedConfig ? <span class="chip chip-blue">Managed config</span> : <span class="chip">Official config</span>}
+              {agent.protocol && <span class="chip">{protocolLabels[agent.protocol]}</span>}
+            </div>
+          </a>
+        ))}
+      </div>
+      <div class="section-actions"><a class="button button-secondary" href={href("explore/")}>Open full Explorer</a></div>
+    </div>
+  </section>
+
+  <section class="cta-band">
+    <div class="shell cta-grid reveal">
+      <div><h2>Understand the flow in the demo, then activate it locally.</h2><p>Download OneAgent for local detection, configuration backups and protocol verification. Team baselines and internal delivery still never take custody of API keys.</p></div>
+      <div class="cta-actions">
+        <a class="button button-primary" href={href("downloads/")}>Download OneAgent</a>
+        <a class="button button-secondary" href={localePath("zh-CN", "enterprise/")}>Explore team services<span class="lang-hint">in Chinese</span></a>
+      </div>
+    </div>
+  </section>
+</BaseLayout>
diff --git a/site/src/pages/en/quickstart/index.astro b/site/src/pages/en/quickstart/index.astro
new file mode 100644
index 00000000..9031a72b
--- /dev/null
+++ b/site/src/pages/en/quickstart/index.astro
@@ -0,0 +1,57 @@
+---
+import BaseLayout from "../../../layouts/BaseLayout.astro";
+import { localePath } from "../../../i18n";
+---
+<BaseLayout
+  title="Quickstart — OneAgent"
+  description="From download to a first verified agent configuration with OneAgent."
+>
+  <header class="page-hero">
+    <div class="shell page-hero-grid">
+      <div>
+        <nav class="breadcrumb" aria-label="Breadcrumb"><a href={localePath("en", "")}>Home</a> / Quickstart</nav>
+        <p class="eyebrow">Six deliberate steps</p>
+        <h1 class="page-title">Succeed once, without reading every config file first.</h1>
+      </div>
+      <div class="page-hero-aside">
+        <strong>Goal</strong>
+        Configure one agent, one provider and one real model protocol — and know exactly what OneAgent wrote.
+      </div>
+    </div>
+  </header>
+  <section class="section-compact">
+    <div class="shell content-grid reveal">
+      <article class="prose">
+        <div class="notice notice-warning">
+          <span class="notice-mark">!</span><div><strong>This is an unsigned technical preview</strong><p>If your operating system blocks it from running, stop there and either wait for a signed build or use the supported from-source path in the repository docs. This page does not describe ways around your system's security policy.</p></div>
+        </div>
+        <h2 id="download">1. Download and verify</h2>
+        <p>Pick the artifact matching your platform and architecture from the download centre. Compute its SHA-256 before running anything, and compare it character by character with the value shown on that page.</p>
+        <h2 id="launch">2. Launch OneAgent</h2>
+        <p>Unpack and run it. The interface is served on your machine's loopback address, never exposed to your LAN or the internet, and the local service exits with the app.</p>
+        <h2 id="agent">3. Choose an agent</h2>
+        <p>Choose the tool you actually intend to use. Agents marked “official guide” still go through the flow, but OneAgent will not dress them up as automatically installed or configured.</p>
+        <h2 id="provider">4. Connect your own provider</h2>
+        <p>Choose a provider or a custom compatible endpoint, and use your own API key. OneAgent offers no shared key, builds no unified model gateway, and never bills you for model usage.</p>
+        <h2 id="probe">5. Test the real protocol</h2>
+        <p>A reachable model list does not mean the agent will work. OneAgent tests the connection using the protocol that agent actually speaks: OpenAI Chat Completions, Anthropic Messages, or OpenAI Responses.</p>
+        <h2 id="review">6. Review what was written</h2>
+        <p>The final page shows each agent's result, where its configuration lives and how to start it. Backups are taken before anything is modified, and errors surface immediately rather than at the agent's first request.</p>
+        <div class="notice notice-info">
+          <span class="notice-mark">i</span><div><strong>Where does the key go?</strong><p>Your key is written only to the local config or OneAgent environment file the target agent needs to work. It never reaches a OneAgent profile, log, screenshot or telemetry event.</p></div>
+        </div>
+        <h2 id="troubleshooting">If something goes wrong</h2>
+        <ul>
+          <li>Agent missing: install it from the official source shown on the page, never from an unverified mirror script.</li>
+          <li>Key rejected: check permissions and balance in the provider's own console. Do not paste the key into a chat or an issue.</li>
+          <li>Protocol mismatch: switch to a model that explicitly supports the agent's protocol, rather than only checking <code>/v1/models</code>.</li>
+          <li>Checksum mismatch: do not run the file. Keep the filename, the download URL and the hash you computed.</li>
+        </ul>
+        <p><a class="button button-primary" href={localePath("en", "downloads/")}>Go to the download centre</a></p>
+      </article>
+      <nav class="side-index" aria-label="On this page">
+        <a href="#download">1. Download and verify</a><a href="#launch">2. Launch</a><a href="#agent">3. Choose an agent</a><a href="#provider">4. Connect a provider</a><a href="#probe">5. Test the protocol</a><a href="#review">6. Review results</a><a href="#troubleshooting">Troubleshooting</a>
+      </nav>
+    </div>
+  </section>
+</BaseLayout>
diff --git a/site/src/pages/en/security/index.astro b/site/src/pages/en/security/index.astro
new file mode 100644
index 00000000..dc4e8e60
--- /dev/null
+++ b/site/src/pages/en/security/index.astro
@@ -0,0 +1,90 @@
+---
+import BaseLayout from "../../../layouts/BaseLayout.astro";
+import { localePath } from "../../../i18n";
+import { getPreviewChannel } from "../../../lib/release-channel";
+const preview = await getPreviewChannel();
+const publishedTarget = preview?.targets.find((target) => target.status === "available") ?? null;
+const publishedArtifact = publishedTarget?.artifacts.find((artifact) => artifact.kind === "binary") ?? null;
+/* The heading ids are shared with the Chinese page on purpose: release-index.json
+   points privacy_policy at security/#privacy and every target's evidence link at
+   security/#release-evidence, and those anchors have to resolve in both locales. */
+---
+<BaseLayout
+  title="Security, privacy and release integrity — OneAgent"
+  description="How OneAgent runs locally, where API keys go, how configuration is backed up, why every channel ships the same build, and what the unsigned preview does not claim."
+>
+  <header class="page-hero">
+    <div class="shell page-hero-grid">
+      <div><nav class="breadcrumb" aria-label="Breadcrumb"><a href={localePath("en", "")}>Home</a> / Security</nav><p class="eyebrow">Trust is inspectable</p><h1 class="page-title">Every boundary here is one you can check yourself.</h1></div>
+      <div class="page-hero-aside"><strong>No cloud account, no traffic relay</strong>Your key goes straight to the provider you picked. Configuration and backups stay on your machine. No application telemetry is collected by default.</div>
+    </div>
+  </header>
+  <section class="section-compact">
+    <div class="shell content-grid reveal">
+      <article class="prose">
+        <h2 id="local">Your data stays on your device</h2>
+        <p>The interface and the API both run on a loopback address. Configuration, backups and state are written on your machine.</p>
+        <p>The local service is not a control plane for anything outside it.</p>
+
+        <h2 id="privacy">A key only goes where it has to</h2>
+        <p>An API key is written to the one file the target agent needs to work: its own configuration, or OneAgent's environment file.</p>
+        <p>Keys never appear in the OneAgent profile, logs, screenshots, web analytics events, or command-line arguments.</p>
+        <p>Where it lands depends on the agent and the operating system. These are the common ones:</p>
+        <ul>
+          <li><code>~/.codex/config.toml</code></li>
+          <li><code>~/.claude/settings.json</code></li>
+          <li><code>~/.config/opencode/opencode.jsonc</code></li>
+          <li><code>~/.config/kilo/kilo.jsonc</code></li>
+          <li><code>~/.oneagent/</code></li>
+        </ul>
+        <p>The launcher lists the real paths before and after every write.</p>
+
+        <h2 id="backups">A backup comes before any change</h2>
+        <p>Before modifying existing configuration, OneAgent writes a timestamped backup.</p>
+        <p>Configuration directories and files holding a key are readable only by the current user. The cleanroom check confirms the real user directory was untouched by the test run.</p>
+
+        <h2 id="distribution">Every channel ships the same package</h2>
+        <p>This site, GitHub Releases, a file host and an internal drive all distribute the identical official build. For a given version, the contents and the SHA-256 match.</p>
+        <p>Channels do not repackage, append promotional content, or re-sign.</p>
+        <p>Third-party agent binaries are not redistributed by OneAgent. They come from the official installer, a mirror with written permission, or your own manual install.</p>
+
+        <h2 id="release-evidence">Current release evidence</h2>
+        {publishedTarget && publishedArtifact ? (
+          <>
+            <p>These values come from the published release metadata on GitHub Releases, so you can check each one against the release page itself.</p>
+            <ul>
+              <li>Channel: <code>technical-preview-unsigned</code></li>
+              <li>Version: <code>{preview?.version}</code></li>
+              <li>Platform: {publishedTarget.platformLabel} {publishedTarget.archLabel}</li>
+              <li>SHA-256: <code>{publishedArtifact.sha256}</code></li>
+              <li>Signing and notarisation: not yet complete, so this is not stable.</li>
+            </ul>
+            <p class="prose-fine">Whether the build was native, and whether a cleanroom run passed, is recorded by the release process — this page does not assert it on the release process's behalf.</p>
+          </>
+        ) : (
+          <p>No artifact has been published on this channel yet, so there is no digest here to check.</p>
+        )}
+
+        <div class="prose-aside">
+          <h2 id="stable">The stable gate</h2>
+          <p>Each platform reaches stable on its own once it qualifies, without waiting for the others.</p>
+          <ul>
+            <li>macOS: Developer ID signature, notarisation, stapled ticket</li>
+            <li>Windows: a valid Authenticode signature</li>
+            <li>Every platform: a native build and cleanroom evidence</li>
+          </ul>
+
+          <h2 id="excluded">Explicitly out of scope</h2>
+          <p>These are not part of the product, and will not be added as features:</p>
+          <ul>
+            <li>VPNs, proxy nodes, or instructions for getting around network restrictions</li>
+            <li>Shared API keys, a unified model gateway, reselling models or API access</li>
+            <li>Unauthorised agent binaries and channel-customised packages</li>
+            <li>Describing an unsigned preview as stable or as security-certified</li>
+          </ul>
+        </div>
+      </article>
+      <nav class="side-index" aria-label="On this page"><a href="#local">Where data lives</a><a href="#privacy">Where keys go</a><a href="#backups">Backups</a><a href="#distribution">One package</a><a href="#release-evidence">Release evidence</a><a href="#stable">Stable gate</a><a href="#excluded">Out of scope</a></nav>
+    </div>
+  </section>
+</BaseLayout>
diff --git a/site/src/pages/enterprise/index.astro b/site/src/pages/enterprise/index.astro
index 215e1ac1..79cdac47 100644
--- a/site/src/pages/enterprise/index.astro
+++ b/site/src/pages/enterprise/index.astro
@@ -12,14 +12,14 @@ const contactHref = businessEmail ? `mailto:${businessEmail}?subject=OneAgent%20
     </div>
   </header>
   <section class="section-compact">
-    <div class="shell service-grid">
+    <div class="shell service-grid reveal">
       <article class="service"><span class="service-number">01 / ENABLE</span><h2>团队启用</h2><ul><li>环境与前置工具盘点</li><li>Agent / Provider 选型</li><li>安装培训与上线检查</li></ul></article>
       <article class="service"><span class="service-number">02 / BASELINE</span><h2>环境标准化</h2><ul><li>批准的 Agent 版本基线</li><li>Provider 配置模板与回滚说明</li><li>官方同包内部镜像流程</li></ul></article>
       <article class="service"><span class="service-number">03 / SUPPORT</span><h2>商业支持</h2><ul><li>发布与升级协助</li><li>兼容性验证</li><li>约定响应时间与 SLA</li></ul></article>
     </div>
   </section>
   <section class="section section-muted">
-    <div class="shell split-callout"><span class="callout-index">BOUNDARY</span><div class="callout-body"><h2>企业服务不等于接管企业的模型流量。</h2><p>OneAgent 不托管企业 API Key，不建立集中代理，不把未授权 Agent 二进制塞进内部镜像。配置和秘密仍由客户设备或客户自己的秘密管理系统持有。</p><a class="button button-primary" href={contactHref}>{businessEmail ? "发送企业合作邮件" : "查看当前联系状态"}</a>{!businessEmail && <p class="hero-note">公开商务邮箱尚未配置；网站不会展示虚构联系方式。</p>}</div></div>
+    <div class="shell split-callout reveal"><span class="callout-index">BOUNDARY</span><div class="callout-body"><h2>企业服务不等于接管企业的模型流量。</h2><p>OneAgent 不托管企业 API Key，不建立集中代理，不把未授权 Agent 二进制塞进内部镜像。配置和秘密仍由客户设备或客户自己的秘密管理系统持有。</p><a class="button button-primary" href={contactHref}>{businessEmail ? "发送企业合作邮件" : "查看当前联系状态"}</a>{!businessEmail && <p class="hero-note">公开商务邮箱尚未配置；网站不会展示虚构联系方式。</p>}</div></div>
   </section>
   <section class="section-compact">
     <div class="narrow prose"><h2>产品化门禁</h2><p>只有在至少获得 3 个设计合作方、其中 2 个付费试点，并且它们反复提出相同需求后，才评估团队模板导入导出、环境合规报告、组织版本策略或内部升级策略。进入产品前必须新增 ADR，重新评估权限与隐私。</p></div>
diff --git a/site/src/pages/explore/index.astro b/site/src/pages/explore/index.astro
new file mode 100644
index 00000000..f95d6f7b
--- /dev/null
+++ b/site/src/pages/explore/index.astro
@@ -0,0 +1,21 @@
+---
+import CompatibilityExplorer from "../../components/CompatibilityExplorer.astro";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+---
+<BaseLayout
+  title="AI 开发环境配置 — OneAgent"
+  description="按平台、安装方式、配置方式、协议、Provider 与示例状态探索 OneAgent 的 Agent 兼容能力。"
+>
+  <section class="page-hero">
+    <div class="shell page-hero-grid">
+      <div>
+        <p class="eyebrow">Agent × Provider × Protocol</p>
+        <h1 class="page-title">从兼容目录，走到明确的激活路径。</h1>
+      </div>
+      <p class="lede">能力来自真实仓库目录；机器状态明确属于示例。筛选组合、打开详情，并把选择作为可分享 URL 保留下来。</p>
+    </div>
+  </section>
+  <section class="section section-compact">
+    <div class="shell"><CompatibilityExplorer /></div>
+  </section>
+</BaseLayout>
diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro
index 18eddcd9..d085abb5 100644
--- a/site/src/pages/index.astro
+++ b/site/src/pages/index.astro
@@ -1,100 +1,88 @@
 ---
-import BaseLayout from "../layouts/BaseLayout.astro";
+import ActivationConsole from "../components/ActivationConsole.astro";
 import AgentMark from "../components/AgentMark.astro";
-import releaseIndexData from "../generated/release-index.json";
-import catalogData from "../generated/catalog.json";
-import { agentDescriptions, groupLabels, protocolLabels } from "../lib/content";
-import type { ReleaseChannel } from "../lib/downloads";
+import HeroParticles from "../components/HeroParticles.astro";
+import BaseLayout from "../layouts/BaseLayout.astro";
+import { catalog } from "../lib/catalog";
+import { localePath } from "../i18n";
+import { useCatalogLabels } from "../i18n/catalog";
+import { protocolLabels } from "../lib/content";
+import { getPreviewChannel } from "../lib/release-channel";
 
-const releaseIndex = releaseIndexData as unknown as { channels: ReleaseChannel[] };
-const preview = releaseIndex.channels.find((channel) => channel.channel === "technical-preview-unsigned")!;
-const catalog = catalogData as any;
+/* null means the release feed had nothing to show — an unpublished fork, or a
+   build that ran without network. The note still has to say what channel this
+   is, because that claim is about the product and does not depend on any
+   particular release existing. */
+const preview = await getPreviewChannel();
+const available = preview?.targets.find((target) => target.status === "available");
 const primaryAgents = catalog.agents.slice(0, 6);
-const available = preview.targets.find((target) => target.status === "available");
+const { agentDescriptions, groupLabels, agentFallbackDescription } = useCatalogLabels("zh-CN");
+const href = (path: string) => localePath("zh-CN", path);
 ---
 <BaseLayout>
   <section class="hero">
+    <HeroParticles />
     <div class="shell hero-copy">
       <div>
         <p class="eyebrow">Local-first · Bring your own key</p>
         <h1 class="display">一个入口，<br /><em>激活你的 AI 开发环境。</em></h1>
       </div>
       <div class="hero-side">
-        <p class="lede">OneAgent 检测、安装并初始化常用 Agent。账号、Provider 和 API Key 始终属于你，配置留在本机。</p>
+        <p class="lede">从 Agent 到 Provider，再到真实协议验证。下面这个示例流程可以直接点，真正的扫描、写入与备份都在本地 OneAgent 里完成。</p>
         <div class="hero-actions">
-          <a class="button button-primary" href="downloads/">下载 OneAgent</a>
-          <a class="button button-secondary" href="quickstart/">查看快速开始</a>
+          <button class="button button-primary" type="button" data-activation-trigger="activation-console" aria-controls="activation-console">开始激活演示</button>
         </div>
-        <p class="hero-note">{preview.version} · {preview.label} · 当前开放 {available?.platformLabel} {available?.archLabel}</p>
+        <p class="hero-note">{preview?.version ? `${preview.version} · ` : ""}未签名技术预览版{available ? ` · 当前开放 ${available.platformLabel} ${available.archLabel}` : ""}</p>
       </div>
     </div>
-    <figure class="product-shot">
-      <img src="images/oneagent-overview.jpg" width="1215" height="690" alt="OneAgent 环境总览，显示 Codex、Claude Code、Cursor、OpenCode、OpenClaw 与 Hermes 的状态" />
-    </figure>
-  </section>
-
-  <section class="trust-strip" aria-label="产品边界">
-    <div class="shell trust-grid">
-      <div class="trust-item"><strong>本地执行</strong><span>配置与备份留在用户设备</span></div>
-      <div class="trust-item"><strong>自己的 Key</strong><span>不提供共享 Key 或统一网关</span></div>
-      <div class="trust-item"><strong>同包分发</strong><span>所有渠道保持相同 SHA-256</span></div>
-      <div class="trust-item"><strong>诚实标注</strong><span>未签名预览版不冒充 Stable</span></div>
-    </div>
+    <ActivationConsole />
   </section>
 
   <section class="section">
-    <div class="shell">
+    <div class="shell reveal">
       <div class="section-heading">
-        <div><p class="eyebrow">First success path</p><h2 class="section-title">从下载到首次成功，只保留必要步骤。</h2></div>
-        <p>不要求注册 OneAgent 账号，不要求把 Key 交给新的中间服务，也不会在安装包里捆绑第三方 Agent。</p>
+        <div><p class="eyebrow">One activation path</p><h2 class="section-title">检测、连接、验证，每一步都能解释。</h2></div>
+        <p>配置、备份与凭证都留在本机。任何写入之前，先验证这个 Agent 真正需要的那个协议。</p>
       </div>
       <div class="steps">
-        <article class="step"><h3>选择 Agent</h3><p>优先展示常用工具，同时保留只能按官方方式安装的 Agent。</p></article>
-        <article class="step"><h3>连接 Provider</h3><p>使用你自己的 Provider 账号与 Key，并在写入配置前验证对应协议。</p></article>
-        <article class="step"><h3>完成并复核</h3><p>查看实际写入位置、备份和下一步命令；失败时得到明确错误而非静默降级。</p></article>
+        <article class="step"><h3>识别环境</h3><p>已安装、待配置、只能走官方流程——三种状态分开列出，而不是压成一个勾。</p></article>
+        <article class="step"><h3>连接 Provider</h3><p>按 Agent 所需协议筛选 Provider，也可以填你自己的端点。兼容等级逐项标明。</p></article>
+        <article class="step"><h3>验证并复核</h3><p>验证通过后，给出 Ready 状态、写入位置、备份情况和下一条命令。</p></article>
       </div>
     </div>
   </section>
 
   <section class="section section-muted">
-    <div class="shell">
+    <div class="shell reveal">
       <div class="section-heading">
-        <div><p class="eyebrow">Compatibility, stated precisely</p><h2 class="section-title">“支持”不是一个模糊的勾。</h2></div>
-        <p>安装、配置和协议分别标注。仅引导的 Agent 仍然可以进入流程，但不会被描述成 OneAgent 自动管理。</p>
+        <div><p class="eyebrow">Compatibility catalog</p><h2 class="section-title">真实目录，不用一张静态兼容表糊弄你。</h2></div>
+        <p>{catalog.agents.length} 个 Agent、{catalog.providers.length} 个公开 Provider，以及 OpenAI Responses、Anthropic Messages 与 Chat Completions 的独立兼容状态。</p>
       </div>
       <div class="agent-list">
-        {primaryAgents.map((agent: any) => (
-          <a class="agent-row" href={`agents/${agent.id}/`}>
+        {primaryAgents.map((agent) => (
+          <a class="agent-row" href={href(`explore/?agent=${agent.id}`)}>
             <AgentMark id={agent.id} name={agent.name} />
             <div><strong>{agent.name}</strong><span class="agent-meta">{groupLabels[agent.group] ?? agent.group}</span></div>
-            <span class="agent-meta">{agentDescriptions[agent.id] ?? "按项目公开能力提供安装或配置支持。"}</span>
+            <span class="agent-meta">{agentDescriptions[agent.id] ?? agentFallbackDescription}</span>
             <div class="agent-status">
-              {agent.support.managedInstall ? <span class="chip chip-green">管理安装</span> : <span class="chip">官方引导</span>}
-              {agent.support.managedConfig ? <span class="chip chip-blue">管理配置</span> : <span class="chip">官方配置</span>}
+              {agent.support.managedInstall ? <span class="chip chip-green">托管安装</span> : <span class="chip">官方引导</span>}
+              {agent.support.managedConfig ? <span class="chip chip-blue">托管配置</span> : <span class="chip">官方配置</span>}
               {agent.protocol && <span class="chip">{protocolLabels[agent.protocol]}</span>}
             </div>
           </a>
         ))}
       </div>
-      <div style="margin-top:28px"><a class="button button-secondary" href="agents/">查看全部 {catalog.agents.length} 个 Agent</a></div>
-    </div>
-  </section>
-
-  <section class="section">
-    <div class="shell split-callout">
-      <span class="callout-index">01 / TRUST</span>
-      <div class="callout-body">
-        <h2>分发不是把一个 ZIP 放到更多地方，而是让每个地方都能证明它是同一个 ZIP。</h2>
-        <p>每个公开产物都带版本、平台、架构、大小和 SHA-256。官网、GitHub Release、网盘或企业云盘只能分发完全相同的官方构建。</p>
-        <a class="button button-secondary" href="security/">查看安全与发行政策</a>
-      </div>
+      <div class="section-actions"><a class="button button-secondary" href={href("explore/")}>打开完整配置目录</a></div>
     </div>
   </section>
 
   <section class="cta-band">
-    <div class="shell cta-grid">
-      <div><h2>先让一个人的环境可靠，再把它标准化到整个团队。</h2><p>团队启用、环境基线、内部镜像与商业支持，不接管企业 API Key。</p></div>
-      <a class="button button-secondary" href="enterprise/">了解企业服务</a>
+    <div class="shell cta-grid reveal">
+      <div><h2>先在示例里看清流程，再在本机真正激活。</h2><p>下载 OneAgent 完成本地检测、配置备份与协议验证；团队基线和内部交付仍然不接管 API Key。</p></div>
+      <div class="cta-actions">
+        <a class="button button-primary" href={href("downloads/")}>下载 OneAgent</a>
+        <a class="button button-secondary" href={href("enterprise/")}>了解团队服务</a>
+      </div>
     </div>
   </section>
 </BaseLayout>
diff --git a/site/src/pages/providers/[id].astro b/site/src/pages/providers/[id].astro
index ffaffdd5..dee6ff5f 100644
--- a/site/src/pages/providers/[id].astro
+++ b/site/src/pages/providers/[id].astro
@@ -1,12 +1,15 @@
 ---
 import BaseLayout from "../../layouts/BaseLayout.astro";
-import catalogData from "../../generated/catalog.json";
-import { protocolLabels, protocolStatusLabels } from "../../lib/content";
+import { catalog } from "../../lib/catalog";
+import { protocolLabels } from "../../lib/content";
+import { localeFromPath } from "../../i18n";
+import { useCatalogLabels } from "../../i18n/catalog";
 
 export function getStaticPaths() {
-  return (catalogData as any).providers.map((provider: any) => ({ params: { id: provider.id }, props: { provider } }));
+  return catalog.providers.map((provider: any) => ({ params: { id: provider.id }, props: { provider } }));
 }
 const { provider } = Astro.props as any;
+const { protocolStatusLabels } = useCatalogLabels(localeFromPath(Astro.url.pathname));
 ---
 <BaseLayout title={`${provider.name} Provider — OneAgent`} description={`${provider.name} 在 OneAgent 中的公开协议接入和商业关系披露。`}>
   <header class="page-hero">
diff --git a/site/src/pages/providers/index.astro b/site/src/pages/providers/index.astro
index 917737cc..01958d52 100644
--- a/site/src/pages/providers/index.astro
+++ b/site/src/pages/providers/index.astro
@@ -1,8 +1,10 @@
 ---
 import BaseLayout from "../../layouts/BaseLayout.astro";
-import catalogData from "../../generated/catalog.json";
-import { protocolLabels, protocolStatusLabels } from "../../lib/content";
-const catalog = catalogData as any;
+import { catalog } from "../../lib/catalog";
+import { protocolLabels } from "../../lib/content";
+import { localeFromPath } from "../../i18n";
+import { useCatalogLabels } from "../../i18n/catalog";
+const { protocolStatusLabels } = useCatalogLabels(localeFromPath(Astro.url.pathname));
 ---
 <BaseLayout title="Provider 目录 — OneAgent" description="查看 OneAgent 的公开 Provider 接入、协议状态和商业关系披露。">
   <header class="page-hero">
@@ -12,7 +14,7 @@ const catalog = catalogData as any;
     </div>
   </header>
   <section class="section-compact">
-    <div class="shell provider-grid">
+    <div class="shell provider-grid reveal">
       {catalog.providers.map((provider: any) => (
         <article class="provider-card">
           <div style="display:flex;justify-content:space-between;gap:20px;align-items:start">
diff --git a/site/src/pages/quickstart/index.astro b/site/src/pages/quickstart/index.astro
index 82a38d72..1b35f372 100644
--- a/site/src/pages/quickstart/index.astro
+++ b/site/src/pages/quickstart/index.astro
@@ -13,7 +13,7 @@ import BaseLayout from "../../layouts/BaseLayout.astro";
     </div>
   </header>
   <section class="section-compact">
-    <div class="shell content-grid">
+    <div class="shell content-grid reveal">
       <article class="prose">
         <div class="notice notice-warning">
           <span class="notice-mark">!</span><div><strong>当前是未签名技术预览版</strong><p>如果操作系统阻止运行，请停止并等待签名版本或使用仓库文档中的受支持源码路径；本文不提供绕过系统安全策略的方法。</p></div>
diff --git a/site/src/pages/release-index.json.ts b/site/src/pages/release-index.json.ts
deleted file mode 100644
index 1028b22d..00000000
--- a/site/src/pages/release-index.json.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import type { APIRoute } from "astro";
-import releaseIndex from "../generated/release-index.json";
-
-export const prerender = true;
-
-export const GET: APIRoute = () =>
-  new Response(`${JSON.stringify(releaseIndex, null, 2)}\n`, {
-    headers: {
-      "Content-Type": "application/json; charset=utf-8",
-      "Cache-Control": "public, max-age=300",
-      "X-Content-Type-Options": "nosniff",
-    },
-  });
diff --git a/site/src/pages/security/index.astro b/site/src/pages/security/index.astro
index 8ccd4da2..0ebb9e02 100644
--- a/site/src/pages/security/index.astro
+++ b/site/src/pages/security/index.astro
@@ -1,40 +1,85 @@
 ---
 import BaseLayout from "../../layouts/BaseLayout.astro";
-import releaseIndexData from "../../generated/release-index.json";
-import type { ReleaseChannel } from "../../lib/downloads";
-const preview = ((releaseIndexData as unknown as { channels: ReleaseChannel[] }).channels.find((channel) => channel.channel === "technical-preview-unsigned"))!;
-const verifiedTarget = preview.targets.find((target) => target.status === "available")!;
-const verifiedArtifact = verifiedTarget.artifacts.find((artifact) => artifact.kind === "binary")!;
+import { getPreviewChannel } from "../../lib/release-channel";
+const preview = await getPreviewChannel();
+const publishedTarget = preview?.targets.find((target) => target.status === "available") ?? null;
+const publishedArtifact = publishedTarget?.artifacts.find((artifact) => artifact.kind === "binary") ?? null;
 ---
 <BaseLayout title="安全、隐私与发行完整性 — OneAgent" description="OneAgent 的本地执行、密钥处理、配置备份、同包分发和未签名预览版边界。">
   <header class="page-hero">
     <div class="shell page-hero-grid">
-      <div><nav class="breadcrumb" aria-label="面包屑"><a href="">首页</a> / 安全与隐私</nav><p class="eyebrow">Trust is inspectable</p><h1 class="page-title">信任来自可以核对的边界。</h1></div>
-      <div class="page-hero-aside"><strong>默认不采集应用遥测</strong>OneAgent 不需要云端账号，不建立模型流量中转，也不把 API Key 发送给 OneAgent 服务。</div>
+      <div><nav class="breadcrumb" aria-label="面包屑"><a href="">首页</a> / 安全与隐私</nav><p class="eyebrow">Trust is inspectable</p><h1 class="page-title">每一条边界都可以自己核对。</h1></div>
+      <div class="page-hero-aside"><strong>没有云端账号，没有流量中转</strong>你的 Key 直接到你选的 Provider，配置和备份留在本机。默认不采集应用遥测。</div>
     </div>
   </header>
   <section class="section-compact">
-    <div class="shell content-grid">
+    <div class="shell content-grid reveal">
       <article class="prose">
-        <h2 id="local">本地执行</h2>
-        <p>Launcher 在本机回环地址上提供界面与 API。配置、备份和状态保存在用户设备；本地服务不作为公网控制面。</p>
-        <h2 id="privacy">API Key 与隐私</h2>
-        <p>API Key 只写入目标 Agent 工作所需的本地配置或 OneAgent 环境文件。Key 不进入 OneAgent profile、日志、截图、网页分析事件或命令行参数。</p>
-        <p>典型写入位置包括 <code>~/.codex/config.toml</code>、<code>~/.claude/settings.json</code>、<code>~/.config/opencode/opencode.jsonc</code>、<code>~/.config/kilo/kilo.jsonc</code> 和 <code>~/.oneagent/</code>。具体路径取决于 Agent 与操作系统，写入前后均由 Launcher 展示。</p>
-        <h2 id="backups">权限与备份</h2>
-        <p>OneAgent 在修改既有配置前创建备份，并把配置目录和包含密钥的文件限制为当前用户可访问。cleanroom 会检查真实用户目录没有被测试流程修改。</p>
-        <h2 id="distribution">同包分发</h2>
-        <p>官网、GitHub Release、网盘和企业云盘只能分发完全相同的 OneAgent 官方构建。同版本的文件内容和 SHA-256 必须一致，渠道不得重新打包、追加推广内容或二次签名。</p>
-        <p>OneAgent 不重新分发第三方 Agent 二进制。Agent 应来自官方安装源、经过书面授权的镜像或用户手动安装。</p>
+        <h2 id="local">数据留在你的设备</h2>
+        <p>界面与 API 都跑在本机回环地址上。配置、备份和状态写在你的设备里。</p>
+        <p>本地服务不对外提供控制面。</p>
+
+        <h2 id="privacy">Key 只去它该去的地方</h2>
+        <p>API Key 只写进目标 Agent 工作所需的那一个文件：它自己的配置，或 OneAgent 的环境文件。</p>
+        <p>Key 不会出现在 OneAgent profile、日志、截图、网页分析事件或命令行参数里。</p>
+        <p>写入位置随 Agent 与操作系统而定，常见的是这几个：</p>
+        <ul>
+          <li><code>~/.codex/config.toml</code></li>
+          <li><code>~/.claude/settings.json</code></li>
+          <li><code>~/.config/opencode/opencode.jsonc</code></li>
+          <li><code>~/.config/kilo/kilo.jsonc</code></li>
+          <li><code>~/.oneagent/</code></li>
+        </ul>
+        <p>每次写入前后，Launcher 都会把实际路径列出来。</p>
+
+        <h2 id="backups">改动之前先备份</h2>
+        <p>修改既有配置前，OneAgent 先创建一份带时间戳的备份。</p>
+        <p>配置目录和含密钥的文件只对当前用户开放。cleanroom 会复核真实用户目录未被测试流程改动。</p>
+
+        <h2 id="distribution">每个渠道都是同一个包</h2>
+        <p>官网、GitHub Release、网盘、企业云盘分发的是完全相同的官方构建。同一版本，文件内容与 SHA-256 一致。</p>
+        <p>渠道不重新打包，不追加推广内容，不二次签名。</p>
+        <p>第三方 Agent 二进制不由 OneAgent 转发。它们来自官方安装源、书面授权的镜像，或你手动安装。</p>
+
         <h2 id="release-evidence">当前发行证据</h2>
-        <div class="notice notice-success"><span class="notice-mark">✓</span><div><strong>macOS arm64 cleanroom 已复核</strong><p>{preview.version} 的当前 {verifiedTarget.platformLabel} {verifiedTarget.archLabel} ZIP 已按精确 SHA-256 完成原生 cleanroom 复核。</p></div></div>
-        <ul><li>渠道：<code>technical-preview-unsigned</code></li><li>SHA-256：<code>{verifiedArtifact.sha256}</code></li><li>签名与公证：尚未完成，因此不是 Stable。</li></ul>
-        <h2 id="stable">Stable 门禁</h2>
-        <p>macOS 需要 Developer ID 签名、公证和 stapled ticket；Windows 需要有效 Authenticode；每个平台还必须有原生构建与 cleanroom 证据。平台可以独立进入 Stable，不用等待所有平台同时完成。</p>
-        <h2 id="excluded">明确排除</h2>
-        <ul><li>VPN、代理节点或绕过网络限制的指导；</li><li>共享 API Key、统一模型网关、模型/API 转售；</li><li>未授权 Agent 二进制和渠道定制包；</li><li>把未签名预览版描述为 Stable 或安全认证版本。</li></ul>
+        {publishedTarget && publishedArtifact ? (
+          <>
+            <p>下面这些值来自 GitHub Releases 已发布的产物元数据，你可以对着发行页逐条核对。</p>
+            <ul>
+              <li>渠道：<code>technical-preview-unsigned</code></li>
+              <li>版本：<code>{preview?.version}</code></li>
+              <li>平台：{publishedTarget.platformLabel} {publishedTarget.archLabel}</li>
+              <li>SHA-256：<code>{publishedArtifact.sha256}</code></li>
+              <li>签名与公证：尚未完成，因此不是 Stable。</li>
+            </ul>
+            {/* 构建来源不在发行元数据里。原生构建与 cleanroom 复核由发布流程执行并记录在
+                仓库中，这个页面只声明它能证明的部分：已发布产物的摘要。 */}
+            <p class="prose-fine">原生构建与 cleanroom 复核的结论记录在发布流程里，不由这个页面代为断言。</p>
+          </>
+        ) : (
+          <p>当前渠道还没有已发布的产物，因此这里没有可核对的摘要。</p>
+        )}
+
+        <div class="prose-aside">
+          <h2 id="stable">Stable 门禁</h2>
+          <p>每个平台各自达标后独立进入 Stable，不必等其他平台。</p>
+          <ul>
+            <li>macOS：Developer ID 签名、公证、stapled ticket</li>
+            <li>Windows：有效的 Authenticode 签名</li>
+            <li>所有平台：原生构建与 cleanroom 证据</li>
+          </ul>
+
+          <h2 id="excluded">明确排除</h2>
+          <p>这些不在产品范围内，也不会作为功能加进来：</p>
+          <ul>
+            <li>VPN、代理节点，或绕过网络限制的指导</li>
+            <li>共享 API Key、统一模型网关、模型或 API 转售</li>
+            <li>未授权的 Agent 二进制与渠道定制包</li>
+            <li>把未签名预览版说成 Stable 或安全认证版本</li>
+          </ul>
+        </div>
       </article>
-      <nav class="side-index" aria-label="本页目录"><a href="#local">本地执行</a><a href="#privacy">Key 与隐私</a><a href="#backups">权限与备份</a><a href="#distribution">同包分发</a><a href="#release-evidence">发行证据</a><a href="#stable">Stable 门禁</a><a href="#excluded">明确排除</a></nav>
+      <nav class="side-index" aria-label="本页目录"><a href="#local">数据位置</a><a href="#privacy">Key 去哪</a><a href="#backups">备份</a><a href="#distribution">同包分发</a><a href="#release-evidence">发行证据</a><a href="#stable">Stable 门禁</a><a href="#excluded">明确排除</a></nav>
     </div>
   </section>
 </BaseLayout>
diff --git a/site/src/styles/global.css b/site/src/styles/global.css
index c54d307b..0b09ecbe 100644
--- a/site/src/styles/global.css
+++ b/site/src/styles/global.css
@@ -1,29 +1,94 @@
+/* Stays `light` so native controls match the light tokens below; .theme-dark
+   flips it to `dark` for itself. */
 :root {
   color-scheme: light;
-  font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "PingFang SC", "Microsoft YaHei", "Helvetica Neue", Arial, sans-serif;
+  font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", "PingFang SC", "Microsoft YaHei", "Helvetica Neue", Arial, sans-serif;
   font-synthesis: none;
+  font-optical-sizing: auto;
   text-rendering: optimizeLegibility;
-  --paper: #f4f3ef;
-  --paper-strong: #eceae4;
+
+  /* Palette mirrors the desktop client's tokens.css so the site and the app
+     a user downloads read as one product. */
+  --paper: #ececef;
+  --paper-strong: #ededf0;
   --surface: #ffffff;
-  --surface-muted: #faf9f6;
-  --ink: #191918;
-  --ink-soft: #5e5d59;
-  --ink-faint: #6b6963;
-  --line: rgba(32, 32, 29, 0.14);
-  --line-strong: rgba(32, 32, 29, 0.24);
-  --blue: #1f5edc;
-  --blue-deep: #174fc4;
-  --blue-soft: #eaf1ff;
-  --green: #247340;
-  --green-soft: #e8f4eb;
-  --orange: #9b520c;
-  --orange-soft: #fff0df;
-  --red: #b4232d;
-  --red-soft: #fff0f0;
-  --radius-control: 7px;
-  --radius-panel: 12px;
-  --shadow-float: 0 32px 80px rgba(26, 30, 40, 0.14), 0 4px 18px rgba(26, 30, 40, 0.08);
+  --surface-muted: #f7f7f9;
+  --surface-pressed: #ededf0;
+  --ink: #1d1d1f;
+  /* Darkened from tokens.css's #6e6e73 / #8e8e93 / #006ee6: those clear AA on
+     the app's white window but not on this page's #ececef ground. */
+  --ink-soft: #636368;
+  --ink-faint: #68686d;
+  --line: rgba(60, 60, 67, 0.18);
+  --line-strong: rgba(60, 60, 67, 0.28);
+  --blue: #007aff;
+  --blue-deep: #0062cc;
+  /* Opaque on purpose: a translucent tint resolves against whatever section
+     background sits behind it, so the chip's contrast drifted per page. */
+  --blue-soft: #e8f0fb;
+  --green: #1c722f;
+  --green-soft: #e9f7ec;
+  --orange: #b25000;
+  --orange-soft: #fff3e7;
+  --red: #d70015;
+  --red-soft: #fff0f1;
+  --radius-control: 6px;
+  --radius-panel: 8px;
+  --radius-window: 12px;
+  --shadow-float: 0 22px 55px rgba(42, 42, 46, 0.16), 0 2px 8px rgba(42, 42, 46, 0.08);
+  --shadow-lift: 0 8px 24px rgba(42, 42, 46, 0.08);
+
+  /* Colours that used to be written inline. Naming them is what lets the dark
+     scheme reach them — a literal in a rule body cannot follow the theme. */
+  --on-accent: #ffffff;
+  --accent-pressed: #00539f;
+  --code-ink: #292b2f;
+  --code-bg: #e8e7e3;
+  --cta-ink: #ffffff;
+  --cta-ink-soft: rgba(255, 255, 255, 0.66);
+  --cta-bg: #1b1d22;
+  --cta-line: rgba(255, 255, 255, 0.32);
+  --selection-bg: #cfdfff;
+  --focus-ring: rgba(36, 103, 242, 0.33);
+  --chip-blue-line: rgba(0, 98, 204, 0.2);
+  --chip-green-line: rgba(28, 114, 47, 0.2);
+  --chip-orange-line: rgba(178, 80, 0, 0.2);
+  --chip-red-line: rgba(215, 0, 21, 0.2);
+  --particle: 0, 98, 204;
+
+  /* Type scale measured off apple.com's compiled marketing stylesheet. The
+     tracking curve is not monotonic: 40px is the 0em neutral point, larger
+     sizes go negative and 21-32px go positive. */
+  --fs-hero: clamp(48px, 7.2vw, 80px);
+  --fs-h1: clamp(40px, 5.6vw, 64px);
+  --fs-h2: clamp(32px, 4.2vw, 48px);
+  --fs-h3: clamp(28px, 3vw, 40px);
+  --fs-h4: clamp(24px, 2.2vw, 32px);
+  --fs-intro: clamp(19px, 1.6vw, 21px);
+  --fs-body: 17px;
+  --fs-caption: 14px;
+  --ls-hero: -0.015em;
+  --ls-h1: -0.009em;
+  --ls-h2: -0.003em;
+  --ls-h3: 0em;
+  --ls-h4: 0.004em;
+  --ls-intro: 0.011em;
+  --lh-hero: 1.05;
+  --lh-h1: 1.0625;
+  --lh-h2: 1.0834;
+  --lh-body: 1.47;
+
+  --measure-text: 734px;
+  --measure-wide: 1068px;
+  --space-section: clamp(80px, 10vw, 160px);
+  --space-block: clamp(32px, 4vw, 64px);
+
+  --ease-apple: cubic-bezier(0.66, 0, 0.1, 1);
+  --ease-enter: cubic-bezier(0, 0, 0.5, 1);
+  --dur-micro: 0.2s;
+  --dur-base: 0.344s;
+  --dur-slow: 0.4s;
+  --blur-material: 20px;
 }
 
 * { box-sizing: border-box; }
@@ -33,26 +98,20 @@ body {
   min-width: 320px;
   color: var(--ink);
   background: var(--paper);
-  font-size: 16px;
-  line-height: 1.6;
+  font-size: var(--fs-body);
+  line-height: var(--lh-body);
+  letter-spacing: 0;
   -webkit-font-smoothing: antialiased;
 }
-body::before {
-  content: "";
-  position: fixed;
-  inset: 0;
-  z-index: -1;
-  pointer-events: none;
-  background-image: radial-gradient(rgba(25, 25, 24, 0.055) 0.55px, transparent 0.55px);
-  background-size: 9px 9px;
-  opacity: 0.34;
-}
 img { display: block; max-width: 100%; height: auto; }
+[hidden] { display: none !important; }
 a { color: inherit; text-decoration: none; }
 button, input, select { font: inherit; }
 button, select { color: inherit; }
-::selection { color: var(--ink); background: #cfdfff; }
+::selection { color: var(--ink); background: var(--selection-bg); }
 
+/* .product-shot is kept on this same measure wherever it changes, so the
+   preview frame stays aligned with the copy above it. */
 .shell { width: min(1180px, calc(100% - 48px)); margin-inline: auto; }
 .narrow { width: min(780px, calc(100% - 48px)); margin-inline: auto; }
 .wide-narrow { width: min(960px, calc(100% - 48px)); margin-inline: auto; }
@@ -63,7 +122,7 @@ button, select { color: inherit; }
   top: 12px;
   z-index: 100;
   padding: 9px 13px;
-  color: #fff;
+  color: var(--on-accent);
   background: var(--blue-deep);
   border-radius: var(--radius-control);
   transform: translateY(-140%);
@@ -75,11 +134,13 @@ button, select { color: inherit; }
   top: 0;
   z-index: 50;
   border-bottom: 1px solid var(--line);
-  background: color-mix(in srgb, var(--paper) 88%, transparent);
-  backdrop-filter: blur(18px) saturate(120%);
+  background: color-mix(in srgb, var(--paper) 82%, transparent);
+  backdrop-filter: blur(var(--blur-material)) saturate(180%);
 }
 .header-inner { min-height: 68px; display: flex; align-items: center; gap: 34px; }
-.wordmark { display: inline-flex; align-items: center; gap: 10px; font-weight: 720; letter-spacing: -0.02em; }
+.wordmark { display: inline-flex; align-items: center; gap: 10px; font-weight: 650; letter-spacing: -0.01em; }
+.wordmark-mark { transition: border-color var(--dur-micro) var(--ease-apple), background-color var(--dur-micro) var(--ease-apple); }
+.wordmark:hover .wordmark-mark { border-color: var(--blue); background: var(--blue-soft); }
 .wordmark-mark {
   width: 34px;
   height: 34px;
@@ -97,8 +158,28 @@ button, select { color: inherit; }
   border-radius: var(--radius-control);
   font-size: 14px;
   font-weight: 560;
+  transition: color var(--dur-micro) var(--ease-apple), background-color var(--dur-micro) var(--ease-apple);
+}
+.desktop-nav a:hover, .desktop-nav a[aria-current="page"], .header-link:hover { color: var(--ink); background: var(--surface); }
+/* Nav links are inline boxes, so a scale would not apply — press reads through
+   the surface instead. */
+.desktop-nav a:active, .header-link:active { background: var(--surface-pressed); transition-duration: 100ms; }
+/* Marks a link whose target has no translation in the current locale. Following
+   it changes language, which is a surprise worth naming before the click rather
+   than after it. Only ever rendered on an English page. */
+.lang-hint {
+  margin-left: 5px;
+  padding: 1px 5px;
+  display: inline-block;
+  border: 1px solid var(--line-strong);
+  border-radius: 999px;
+  color: var(--ink-faint);
+  font-size: 10px;
+  font-weight: 500;
+  letter-spacing: 0;
+  vertical-align: 1px;
+  white-space: nowrap;
 }
-.desktop-nav a:hover, .desktop-nav a[aria-current="page"], .header-link:hover { color: var(--ink); background: rgba(255,255,255,.62); }
 .header-actions { margin-left: auto; display: flex; align-items: center; gap: 7px; }
 .mobile-menu { display: none; position: relative; }
 .mobile-menu summary { list-style: none; cursor: pointer; padding: 7px 9px; font-size: 14px; font-weight: 650; }
@@ -115,8 +196,9 @@ button, select { color: inherit; }
   box-shadow: var(--shadow-float);
   border-radius: var(--radius-panel);
 }
-.mobile-menu nav a { padding: 10px 12px; border-radius: 7px; }
+.mobile-menu nav a { padding: 10px 12px; border-radius: var(--radius-control); transition: background-color var(--dur-micro) var(--ease-apple); }
 .mobile-menu nav a:hover { background: var(--surface-muted); }
+.mobile-menu nav a:active { background: var(--surface-pressed); transition-duration: 100ms; }
 
 .button {
   min-height: 44px;
@@ -127,59 +209,80 @@ button, select { color: inherit; }
   gap: 9px;
   border: 1px solid transparent;
   border-radius: var(--radius-control);
-  font-size: 14px;
-  font-weight: 680;
+  font-size: var(--fs-caption);
+  font-weight: 600;
   line-height: 1;
   cursor: pointer;
-  transition: transform 140ms ease, background-color 140ms ease, border-color 140ms ease, color 140ms ease;
+  transition: transform var(--dur-micro) var(--ease-apple), background-color var(--dur-micro) var(--ease-apple), border-color var(--dur-micro) var(--ease-apple), color var(--dur-micro) var(--ease-apple);
 }
 .button:hover { transform: translateY(-1px); }
-.button:active { transform: translateY(0); }
-.button-primary { color: #fff; background: var(--blue); border-color: var(--blue); }
-.button-primary:hover { background: var(--blue-deep); border-color: var(--blue-deep); }
+/* Feedback belongs on the press, not the release, and it has to be fast enough
+   not to read as lag. */
+.button:active { transform: scale(0.97); transition-duration: 100ms; }
+/* --blue is Apple's system blue, but white on it is only 4.02:1 at this text
+   size; --blue-deep carries the fill so the label clears AA. */
+.button-primary { color: var(--on-accent); background: var(--blue-deep); border-color: var(--blue-deep); }
+.button-primary:hover { background: var(--accent-pressed); border-color: var(--accent-pressed); }
 .button-secondary { color: var(--ink); background: var(--surface); border-color: var(--line-strong); }
 .button-secondary:hover { background: var(--surface-muted); }
 .button-small { min-height: 36px; padding-inline: 13px; font-size: 13px; }
 .button-text { min-height: auto; padding: 2px 0; color: var(--blue-deep); border: 0; }
+/* Overrides .button's lift: a text link sliding sideways reads as "go here",
+   where a vertical hop reads as a button. */
+.button-text:hover { transform: translateX(3px); }
 .button[aria-disabled="true"] { color: var(--ink-faint); background: var(--paper-strong); border-color: var(--line); cursor: not-allowed; transform: none; }
 
-.eyebrow { margin: 0 0 14px; color: var(--blue-deep); font-size: 12px; font-weight: 760; letter-spacing: .12em; text-transform: uppercase; }
+.eyebrow { margin: 0 0 14px; color: var(--blue-deep); font-size: 12px; font-weight: 700; letter-spacing: .12em; text-transform: uppercase; }
 .display {
   margin: 0;
-  max-width: 810px;
-  font-size: clamp(46px, 6.4vw, 82px);
-  line-height: .98;
-  letter-spacing: -0.063em;
-  font-weight: 760;
+  max-width: 900px;
+  font-size: var(--fs-hero);
+  line-height: var(--lh-hero);
+  letter-spacing: var(--ls-hero);
+  font-weight: 600;
 }
 .display em { color: var(--blue); font-style: normal; }
-.page-title { margin: 0; font-size: clamp(39px, 5vw, 62px); line-height: 1.04; letter-spacing: -.05em; font-weight: 750; }
-.section-title { margin: 0; max-width: 720px; font-size: clamp(31px, 4vw, 48px); line-height: 1.08; letter-spacing: -.042em; font-weight: 735; }
-.card-title { margin: 0; font-size: 20px; line-height: 1.25; letter-spacing: -.025em; }
-.lede { margin: 24px 0 0; max-width: 680px; color: var(--ink-soft); font-size: clamp(18px, 2.2vw, 23px); line-height: 1.55; letter-spacing: -.018em; }
+.page-title { margin: 0; font-size: var(--fs-h1); line-height: var(--lh-h1); letter-spacing: var(--ls-h1); font-weight: 600; }
+.section-title { margin: 0; max-width: var(--measure-text); font-size: var(--fs-h2); line-height: var(--lh-h2); letter-spacing: var(--ls-h2); font-weight: 600; }
+.card-title { margin: 0; font-size: 21px; line-height: 1.25; letter-spacing: .011em; font-weight: 600; }
+.lede { margin: 24px 0 0; max-width: var(--measure-text); color: var(--ink-soft); font-size: var(--fs-intro); line-height: 1.42; letter-spacing: var(--ls-intro); }
 .prose { color: var(--ink-soft); }
-.prose h2, .prose h3 { color: var(--ink); letter-spacing: -.025em; }
-.prose h2 { margin-top: 64px; font-size: 30px; }
-.prose h3 { margin-top: 36px; font-size: 20px; }
-.prose p, .prose li { max-width: 72ch; }
-.prose a { color: var(--blue-deep); text-decoration: underline; text-underline-offset: 3px; }
-.prose code, code.inline { padding: 2px 5px; overflow-wrap: anywhere; border: 1px solid var(--line); border-radius: 4px; background: rgba(255,255,255,.7); color: var(--ink); font: 0.88em ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; }
-
-.hero { padding: 104px 0 0; overflow: hidden; }
-.hero-copy { display: grid; grid-template-columns: minmax(0, 1.02fr) minmax(360px, .76fr); align-items: end; gap: 72px; }
+.prose h2, .prose h3 { color: var(--ink); font-weight: 600; }
+.prose h2 { margin-top: 64px; font-size: var(--fs-h4); letter-spacing: var(--ls-h4); }
+.prose h3 { margin-top: 36px; font-size: 21px; letter-spacing: .011em; }
+.prose p, .prose li { max-width: var(--measure-text); }
+/* :not(.button) keeps this from overriding .button-primary's white text —
+   both selectors are 0-2-0 and this one used to win on order alone. */
+.prose a:not(.button) { color: var(--blue-deep); text-decoration: underline; text-underline-offset: 3px; }
+.prose code, code.inline { padding: 2px 5px; overflow-wrap: anywhere; border: 1px solid var(--line); border-radius: 4px; background: var(--surface); color: var(--ink); font: 0.88em ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; }
+/* Reference material that belongs on the page but should not compete with it:
+   the boundary and gating facts a reader consults rather than reads through.
+   Kept at full contrast — only the heading scale and leading step down. */
+.prose-aside { margin-top: 72px; padding-top: 8px; border-top: 1px solid var(--line-strong); }
+.prose-aside h2 { margin-top: 40px; font-size: 19px; letter-spacing: .006em; }
+.prose-aside p, .prose-aside li { font-size: 15px; }
+
+/* position + overflow:hidden keep the absolutely positioned particle canvas
+   from widening the document — e2e asserts scrollWidth <= clientWidth. */
+.hero { position: relative; padding: 104px 0 var(--space-block); overflow: hidden; }
+.hero-copy { position: relative; z-index: 1; display: grid; grid-template-columns: minmax(0, 1.02fr) minmax(360px, .76fr); align-items: end; gap: 72px; }
 .hero-side { padding-bottom: 5px; }
 .hero-actions { margin-top: 34px; display: flex; flex-wrap: wrap; gap: 10px; }
 .hero-note { margin: 18px 0 0; color: var(--ink-faint); font-size: 13px; }
+/* Shares .shell's measure so the frame's edges line up with the copy above it
+   and the trust strip below. It used to be 1215px against the shell's 1180px,
+   which read as a misalignment rather than as a deliberately wider layer. */
 .product-shot {
-  width: min(1215px, calc(100% - 48px));
+  width: min(1180px, calc(100% - 48px));
   margin: 74px auto 0;
   padding: 9px;
-  background: rgba(255,255,255,.62);
-  border: 1px solid var(--line-strong);
-  border-radius: 17px;
+  background: var(--surface);
+  border: 1px solid var(--line);
+  border-radius: var(--radius-window);
   box-shadow: var(--shadow-float);
 }
-.product-shot img { width: 100%; border-radius: 10px; }
+/* The activation console owns its internal layout while this shared frame keeps
+   its edges aligned with the hero copy in every locale. */
 
 .trust-strip { padding: 34px 0 0; }
 .trust-grid { display: grid; grid-template-columns: repeat(4, 1fr); border-block: 1px solid var(--line); }
@@ -188,66 +291,92 @@ button, select { color: inherit; }
 .trust-item strong { display: block; margin-bottom: 3px; font-size: 14px; }
 .trust-item span { color: var(--ink-soft); font-size: 13px; }
 
-.section { padding: 120px 0; }
-.section-compact { padding: 82px 0; }
-.section-muted { background: rgba(255,255,255,.46); border-block: 1px solid var(--line); }
+.section { padding: var(--space-section) 0; }
+.section-compact { padding: calc(var(--space-section) * 0.62) 0; }
+.section-muted { background: var(--surface-muted); border-block: 1px solid var(--line); }
 .section-heading { display: flex; align-items: end; justify-content: space-between; gap: 34px; margin-bottom: 52px; }
 .section-heading p { max-width: 450px; margin: 0; color: var(--ink-soft); }
 
 .steps { counter-reset: step; display: grid; grid-template-columns: repeat(3, 1fr); gap: 0; border-top: 1px solid var(--line-strong); }
 .step { counter-increment: step; padding: 30px 32px 0 0; min-height: 210px; border-bottom: 1px solid var(--line); }
 .step + .step { padding-left: 32px; border-left: 1px solid var(--line); }
-.step::before { content: "0" counter(step); display: block; margin-bottom: 52px; color: var(--blue); font: 650 13px ui-monospace, SFMono-Regular, Menlo, monospace; }
-.step h3 { margin: 0 0 9px; font-size: 20px; letter-spacing: -.025em; }
-.step p { margin: 0; color: var(--ink-soft); font-size: 14px; }
+.step::before { content: "0" counter(step); display: block; margin-bottom: 52px; color: var(--blue-deep); font: 650 13px ui-monospace, SFMono-Regular, Menlo, monospace; }
+.step h3 { margin: 0 0 9px; font-size: 21px; letter-spacing: .011em; font-weight: 600; }
+.step p { margin: 0; color: var(--ink-soft); font-size: var(--fs-caption); }
 
 .agent-list { display: grid; border-top: 1px solid var(--line-strong); }
-.agent-row { min-height: 86px; padding: 18px 8px; display: grid; grid-template-columns: 42px minmax(160px, 1fr) minmax(240px, 1.4fr) auto; align-items: center; gap: 16px; border-bottom: 1px solid var(--line); transition: background-color 140ms ease; }
-.agent-row:hover { background: rgba(255,255,255,.48); }
+.agent-row { min-height: 86px; padding: 18px 8px; display: grid; grid-template-columns: 42px minmax(160px, 1fr) minmax(240px, 1.4fr) auto; align-items: center; gap: 16px; border-bottom: 1px solid var(--line); transition: background-color var(--dur-micro) var(--ease-apple), box-shadow var(--dur-micro) var(--ease-apple); }
+.agent-row:hover { background: var(--surface); box-shadow: inset 3px 0 0 var(--blue); }
+.agent-row:active { background: var(--surface-pressed); transition-duration: 100ms; }
 .agent-row strong { display: block; letter-spacing: -.015em; }
 .agent-meta { color: var(--ink-soft); font-size: 13px; }
 .agent-status { display: flex; flex-wrap: wrap; gap: 6px; }
 .agent-mark-wrap { width: 34px; height: 34px; display: grid; place-items: center; background: var(--surface); border: 1px solid var(--line); border-radius: 8px; }
 .agent-mark-wrap img { width: var(--mark-size); height: var(--mark-size); object-fit: contain; }
-.agent-fallback { font-size: 13px; font-weight: 720; }
+.agent-fallback { font-size: 13px; font-weight: 650; }
 
-.chip { min-height: 26px; padding: 3px 8px; display: inline-flex; align-items: center; gap: 5px; border: 1px solid var(--line); border-radius: 999px; color: var(--ink-soft); background: rgba(255,255,255,.68); font-size: 11px; font-weight: 650; white-space: nowrap; }
-.chip-blue { color: var(--blue-deep); background: var(--blue-soft); border-color: rgba(36,103,242,.18); }
-.chip-green { color: var(--green); background: var(--green-soft); border-color: rgba(36,115,64,.17); }
-.chip-orange { color: var(--orange); background: var(--orange-soft); border-color: rgba(155,82,12,.17); }
-.chip-red { color: var(--red); background: var(--red-soft); border-color: rgba(180,35,45,.17); }
+.chip { min-height: 26px; padding: 3px 8px; display: inline-flex; align-items: center; gap: 5px; border: 1px solid var(--line); border-radius: 999px; color: var(--ink-soft); background: var(--surface); font-size: 11px; font-weight: 600; white-space: nowrap; }
+.chip-blue { color: var(--blue-deep); background: var(--blue-soft); border-color: var(--chip-blue-line); }
+.chip-green { color: var(--green); background: var(--green-soft); border-color: var(--chip-green-line); }
+.chip-orange { color: var(--orange); background: var(--orange-soft); border-color: var(--chip-orange-line); }
+.chip-red { color: var(--red); background: var(--red-soft); border-color: var(--chip-red-line); }
 
 .split-callout { display: grid; grid-template-columns: .78fr 1.22fr; gap: 72px; align-items: start; }
-.callout-index { color: var(--blue); font: 650 13px ui-monospace, SFMono-Regular, Menlo, monospace; }
+.callout-index { color: var(--blue-deep); font: 650 13px ui-monospace, SFMono-Regular, Menlo, monospace; }
 .callout-body { padding-top: 1px; }
-.callout-body h2 { margin: 0 0 20px; font-size: clamp(32px,4vw,50px); line-height: 1.08; letter-spacing: -.045em; }
-.callout-body p { max-width: 650px; color: var(--ink-soft); font-size: 18px; }
+.callout-body h2 { margin: 0 0 20px; font-size: var(--fs-h2); line-height: var(--lh-h2); letter-spacing: var(--ls-h2); font-weight: 600; }
+.callout-body p { max-width: var(--measure-text); color: var(--ink-soft); font-size: var(--fs-intro); letter-spacing: var(--ls-intro); }
 
 .page-hero { padding: 92px 0 66px; border-bottom: 1px solid var(--line); }
 .page-hero-grid { display: grid; grid-template-columns: 1fr .55fr; gap: 70px; align-items: end; }
 .page-hero-aside { padding-bottom: 5px; color: var(--ink-soft); }
 .page-hero-aside strong { display: block; margin-bottom: 8px; color: var(--ink); }
 .breadcrumb { margin-bottom: 24px; color: var(--ink-faint); font-size: 13px; }
+.breadcrumb a { transition: color var(--dur-micro) var(--ease-apple); }
 .breadcrumb a:hover { color: var(--ink); }
 
-.notice { padding: 17px 18px; display: flex; gap: 12px; align-items: flex-start; border: 1px solid var(--line); background: rgba(255,255,255,.62); font-size: 14px; }
+.notice { padding: 17px 18px; display: flex; gap: 12px; align-items: flex-start; border: 1px solid var(--line); border-radius: var(--radius-panel); background: var(--surface); font-size: var(--fs-caption); }
 .notice strong { display: block; color: var(--ink); }
 .notice p { margin: 2px 0 0; color: var(--ink-soft); }
-.notice-warning { background: var(--orange-soft); border-color: rgba(155,82,12,.22); }
-.notice-info { background: var(--blue-soft); border-color: rgba(36,103,242,.2); }
-.notice-success { background: var(--green-soft); border-color: rgba(36,115,64,.2); }
-.notice-mark { flex: 0 0 auto; width: 22px; height: 22px; display: grid; place-items: center; border: 1px solid currentColor; border-radius: 50%; font-size: 12px; font-weight: 760; }
+.notice-warning { background: var(--orange-soft); border-color: var(--chip-orange-line); }
+.notice-info { background: var(--blue-soft); border-color: var(--chip-blue-line); }
+.notice-success { background: var(--green-soft); border-color: var(--chip-green-line); }
+.notice-mark { flex: 0 0 auto; width: 22px; height: 22px; display: grid; place-items: center; border: 1px solid currentColor; border-radius: 50%; font-size: 12px; font-weight: 650; }
 
 .download-layout { display: grid; grid-template-columns: 260px minmax(0,1fr); gap: 54px; align-items: start; }
 .download-layout > * { min-width: 0; }
 .platform-control { position: sticky; top: 98px; }
-.platform-control label { display: block; margin-bottom: 8px; font-size: 13px; font-weight: 680; }
-.platform-control select { width: 100%; min-height: 44px; padding: 0 36px 0 12px; border: 1px solid var(--line-strong); border-radius: var(--radius-control); background: var(--surface); }
+.platform-picker { margin: 0; padding: 0; border: 0; display: grid; gap: 8px; }
+.platform-picker legend { padding: 0; margin-bottom: 10px; font-size: 13px; font-weight: 600; }
+.platform-option {
+  padding: 12px 13px;
+  display: grid;
+  grid-template-columns: 16px minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 11px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius-panel);
+  background: var(--surface);
+  cursor: pointer;
+  transition: border-color var(--dur-micro) var(--ease-apple), background-color var(--dur-micro) var(--ease-apple);
+}
+.platform-option:hover { border-color: var(--line-strong); }
+.platform-option:active { background: var(--surface-pressed); transition-duration: 100ms; }
+/* Keeping the real radio (rather than hiding it behind a drawn circle) is what
+   gives this arrow-key navigation, form semantics and focus for free. */
+.platform-option input { width: 16px; height: 16px; margin: 0; accent-color: var(--blue-deep); }
+.platform-option:has(input:checked) { border-color: var(--blue-deep); background: var(--blue-soft); }
+/* The ring belongs on the card, not the 16px dot inside it. */
+.platform-option:has(input:focus-visible) { outline: 3px solid var(--focus-ring); outline-offset: 3px; }
+.platform-option input:focus-visible { outline: none; }
+.platform-option-body { display: grid; gap: 1px; min-width: 0; }
+.platform-option-name { font-size: 14px; font-weight: 600; }
+.platform-option-arch { color: var(--ink-soft); font-size: 12px; }
 .detected-note { margin: 10px 0 0; color: var(--ink-faint); font-size: 12px; }
 .release-panel { display: none; }
 .release-panel.is-active { display: block; }
 .release-head { display: flex; justify-content: space-between; align-items: start; gap: 24px; padding-bottom: 26px; border-bottom: 1px solid var(--line-strong); }
-.release-head h2 { margin: 0 0 6px; font-size: 30px; letter-spacing: -.035em; }
+.release-head h2 { margin: 0 0 6px; font-size: 28px; letter-spacing: .004em; font-weight: 600; }
 .release-head p { margin: 0; color: var(--ink-soft); }
 .release-meta-grid { display: grid; grid-template-columns: repeat(2, 1fr); margin: 0; }
 .release-meta-grid div { padding: 22px 0; border-bottom: 1px solid var(--line); }
@@ -257,8 +386,8 @@ button, select { color: inherit; }
 .download-action { margin: 28px 0; display: flex; flex-wrap: wrap; align-items: center; gap: 10px; }
 .hash-block { margin-top: 24px; }
 .hash-row { display: grid; grid-template-columns: minmax(0,1fr) auto; gap: 8px; }
-.hash-value, .code-block { margin: 0; padding: 14px 15px; overflow-x: auto; color: #292b2f; background: #e8e7e3; border: 1px solid var(--line); border-radius: 7px; font: 12px/1.55 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; }
-.copy-button { padding: 0 12px; border: 1px solid var(--line-strong); border-radius: 7px; background: var(--surface); cursor: pointer; font-size: 12px; font-weight: 650; }
+.hash-value, .code-block { margin: 0; padding: 14px 15px; overflow-x: auto; color: var(--code-ink); background: var(--code-bg); border: 1px solid var(--line); border-radius: var(--radius-control); font: 12px/1.55 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; }
+.copy-button { padding: 0 12px; border: 1px solid var(--line-strong); border-radius: var(--radius-control); background: var(--surface); cursor: pointer; font-size: 12px; font-weight: 600; transition: background-color var(--dur-micro) var(--ease-apple); }
 .copy-button:hover { background: var(--surface-muted); }
 .unavailable-panel { padding: 38px 0; }
 .unavailable-panel h3 { margin: 0 0 7px; font-size: 23px; }
@@ -267,8 +396,10 @@ button, select { color: inherit; }
 .content-grid { display: grid; grid-template-columns: minmax(0,1fr) 280px; gap: 68px; align-items: start; }
 .content-grid > * { min-width: 0; }
 .side-index { position: sticky; top: 98px; border-top: 1px solid var(--line-strong); }
-.side-index a { padding: 11px 0; display: block; color: var(--ink-soft); border-bottom: 1px solid var(--line); font-size: 13px; }
-.side-index a:hover { color: var(--ink); }
+/* translate rather than padding so the hover stays on the compositor instead of
+   reflowing the sticky column on every pointer move. */
+.side-index a { padding: 11px 0; display: block; color: var(--ink-soft); border-bottom: 1px solid var(--line); font-size: 13px; transition: color var(--dur-micro) var(--ease-apple), transform var(--dur-micro) var(--ease-apple); }
+.side-index a:hover { color: var(--ink); transform: translateX(4px); }
 
 .detail-grid { display: grid; grid-template-columns: 1fr 1fr; border-top: 1px solid var(--line-strong); }
 .detail-cell { min-height: 142px; padding: 26px 28px 28px 0; border-bottom: 1px solid var(--line); }
@@ -278,8 +409,9 @@ button, select { color: inherit; }
 .detail-cell p { margin: 7px 0 0; color: var(--ink-soft); font-size: 13px; }
 
 .provider-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 18px; }
-.provider-card { min-height: 250px; padding: 28px; display: flex; flex-direction: column; background: rgba(255,255,255,.72); border: 1px solid var(--line); }
-.provider-card h2 { margin: 0; font-size: 27px; letter-spacing: -.035em; }
+.provider-card { min-height: 250px; padding: 28px; display: flex; flex-direction: column; background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius-panel); transition: border-color var(--dur-micro) var(--ease-apple), box-shadow var(--dur-micro) var(--ease-apple), transform var(--dur-micro) var(--ease-apple); }
+.provider-card:hover { border-color: var(--line-strong); box-shadow: var(--shadow-lift); transform: translateY(-2px); }
+.provider-card h2 { margin: 0; font-size: 28px; letter-spacing: .004em; font-weight: 600; }
 .provider-card p { color: var(--ink-soft); }
 .provider-card .agent-status { margin-top: 14px; }
 .provider-card .button-text { margin-top: auto; align-self: flex-start; }
@@ -293,22 +425,23 @@ button, select { color: inherit; }
 .service-grid { display: grid; grid-template-columns: repeat(3,1fr); border-top: 1px solid var(--line-strong); }
 .service { padding: 30px 30px 34px 0; border-bottom: 1px solid var(--line); }
 .service + .service { padding-left: 30px; border-left: 1px solid var(--line); }
-.service-number { color: var(--blue); font: 650 12px ui-monospace, SFMono-Regular, Menlo, monospace; }
-.service h2 { margin: 58px 0 10px; font-size: 24px; letter-spacing: -.03em; }
-.service p, .service li { color: var(--ink-soft); font-size: 14px; }
+.service-number { color: var(--blue-deep); font: 650 12px ui-monospace, SFMono-Regular, Menlo, monospace; }
+.service h2 { margin: 58px 0 10px; font-size: var(--fs-h4); letter-spacing: var(--ls-h4); font-weight: 600; }
+.service p, .service li { color: var(--ink-soft); font-size: var(--fs-caption); }
 .service ul { padding-left: 18px; }
 
-.cta-band { padding: 76px 0; color: #fff; background: #1b1d22; }
+.cta-band { padding: 76px 0; color: var(--cta-ink); background: var(--cta-bg); }
 .cta-grid { display: grid; grid-template-columns: 1fr auto; gap: 40px; align-items: center; }
-.cta-band h2 { margin: 0; max-width: 700px; font-size: clamp(34px,4.5vw,56px); line-height: 1.08; letter-spacing: -.045em; }
-.cta-band p { margin: 15px 0 0; color: rgba(255,255,255,.66); }
-.cta-band .button-secondary { border-color: rgba(255,255,255,.32); }
+.cta-band h2 { margin: 0; max-width: var(--measure-text); font-size: var(--fs-h2); line-height: var(--lh-h2); letter-spacing: var(--ls-h2); font-weight: 600; }
+.cta-band p { margin: 15px 0 0; color: var(--cta-ink-soft); }
+.cta-band .button-secondary { border-color: var(--cta-line); }
 
 .site-footer { padding: 70px 0 24px; border-top: 1px solid var(--line); background: var(--paper-strong); }
 .footer-grid { display: grid; grid-template-columns: 2fr repeat(3,1fr); gap: 50px; }
 .footer-grid > div:not(.footer-brand) { display: grid; align-content: start; gap: 8px; }
 .footer-grid strong { margin-bottom: 6px; font-size: 13px; }
 .footer-grid a:not(.wordmark), .footer-grid p { color: var(--ink-soft); font-size: 13px; }
+.footer-grid a { transition: color var(--dur-micro) var(--ease-apple); }
 .footer-grid a:hover { color: var(--ink); }
 .footer-brand p { max-width: 330px; margin: 17px 0 0; }
 .footer-brand .footer-fine { color: var(--ink-faint); }
@@ -334,13 +467,12 @@ button, select { color: inherit; }
 }
 
 @media (max-width: 680px) {
-  .shell, .narrow, .wide-narrow { width: min(100% - 28px, 1180px); }
+  .shell, .narrow, .wide-narrow, .product-shot { width: min(100% - 28px, 1180px); }
   .site-header .button { display: none; }
   .header-inner { min-height: 60px; gap: 12px; }
   .hero { padding-top: 58px; }
   .display { font-size: clamp(43px, 14vw, 63px); }
-  .product-shot { width: calc(100% - 14px); margin-top: 50px; padding: 5px; border-radius: 12px; }
-  .product-shot img { border-radius: 8px; }
+  .product-shot { margin-top: 50px; padding: 5px; border-radius: var(--radius-panel); }
   .trust-grid { grid-template-columns: 1fr; }
   .trust-item, .trust-item + .trust-item, .trust-item:nth-child(3) { padding: 18px 0; border-left: 0; border-top: 1px solid var(--line); }
   .trust-item:first-child { border-top: 0; }
@@ -366,8 +498,190 @@ button, select { color: inherit; }
   .footer-bottom { display: grid; }
 }
 
+/* Scroll-driven reveal. Browsers without animation-timeline (Firefox as of
+   2026-07) never enter the @supports block, so .reveal stays at its static
+   painted state rather than needing a JS fallback.
+
+   Deliberately transform-only: fading text through partial opacity drops its
+   effective contrast below AA for the whole scroll range, and a reader who
+   stops mid-entry is left with unreadable copy. */
+@supports (animation-timeline: view()) {
+  @media not (prefers-reduced-motion: reduce) {
+    .reveal {
+      animation: reveal-in linear both;
+      animation-timeline: view();
+      animation-range: entry 0% entry 55%;
+      will-change: transform;
+    }
+  }
+}
+@keyframes reveal-in {
+  from { transform: translateY(22px); }
+}
+
+/* First-paint entrance for the hero, staggered in reading order.
+
+   Uses --ease-enter, not --ease-apple: the latter is a slow-in/fast-out curve
+   meant for elements leaving or for state changes, and on an entrance it holds
+   the element almost still before snapping — legible as "something moved" but
+   not as a direction. An entrance needs its speed at the start.
+
+   No opacity, deliberately. Fading in is the obvious way to make an entrance
+   read as "arriving", but measured mid-flight it puts the primary button at
+   1.37:1 and the h1 at 1.5:1 — even when the ramp is confined to the first
+   quarter, that window is long enough to be read and short enough to be
+   missed in review. Distance and curve carry the motion instead. */
+@media not (prefers-reduced-motion: reduce) {
+  .hero .eyebrow,
+  .hero .display,
+  .hero .lede,
+  .hero .hero-actions,
+  .hero .hero-note,
+  .product-shot {
+    animation: hero-rise 620ms var(--ease-enter) both;
+  }
+  .hero .display { animation-delay: 70ms; }
+  .hero .lede { animation-delay: 160ms; }
+  .hero .hero-actions { animation-delay: 230ms; }
+  .hero .hero-note { animation-delay: 290ms; }
+  .product-shot { animation-delay: 360ms; }
+}
+
+@keyframes hero-rise {
+  from { transform: translateY(var(--hero-rise-from, 40px)); }
+}
+
+/* Measured at 375px, the tightest gap between two staggered lines is 14px
+   (eyebrow→h1) and buttons→release-note is 18px. Any travel past that lets one
+   line cross into the next mid-flight and obscure it, and a travel under it is
+   too small to perceive — there is no distance that is both safe and visible
+   once the hero stacks. So narrow screens animate the block as a whole: the
+   lines keep their relative positions, so nothing can overlap. */
+@media (max-width: 680px) {
+  .hero .eyebrow,
+  .hero .display,
+  .hero .lede,
+  .hero .hero-actions,
+  .hero .hero-note { animation: none; }
+  .hero-copy { animation: hero-rise 520ms var(--ease-enter) both; }
+  .product-shot { animation-delay: 180ms; }
+}
+
+/* Cross-document view transitions, replacing the white flash between pages.
+   This is the native MPA path, not Astro's <ClientRouter />: it ships no
+   client-side router, leaves every existing script untouched, and degrades to
+   the current full-page load where unsupported (Firefox as of 2026-07). */
+@view-transition { navigation: auto; }
+
+/* The chrome is identical on every page, so naming it lets the browser hold it
+   still while only the main content crossfades — without these it would fade
+   out and back in on every navigation. */
+.site-header { view-transition-name: site-header; }
+.site-footer { view-transition-name: site-footer; }
+
+@media not (prefers-reduced-motion: reduce) {
+  ::view-transition-old(root) {
+    animation: vt-out var(--dur-micro) var(--ease-apple) both;
+  }
+  ::view-transition-new(root) {
+    animation: vt-in var(--dur-base) var(--ease-apple) both;
+  }
+}
+
+/* Held to a small translate: a page-level slide that travels far enough to
+   notice also reads as sluggish on every single click. */
+@keyframes vt-out {
+  to { opacity: 0; transform: translateY(-6px); }
+}
+@keyframes vt-in {
+  from { opacity: 0; transform: translateY(10px); }
+}
+
+/* Dark scheme. Every value here was measured against its own surface rather
+   than derived by inverting the light palette: Apple's #007aff drops to 4.28:1
+   on a dark card and fails, so the accent is lifted to #3d9bff for text while
+   the button keeps the darker fill that white sits on at 5.80:1.
+
+   Declared before the prefers-contrast block below, whose :root override is
+   written in light-scheme literals and would otherwise win on order. */
+.theme-dark {
+  color-scheme: dark;
+
+  --paper: #0f1418;
+  --paper-strong: #0b0f12;
+  --surface: #161c21;
+  --surface-muted: #1b2228;
+  --surface-pressed: #212a31;
+  --ink: #f5f6f7;
+  --ink-soft: #adb3b9;
+  --ink-faint: #9aa1a8;
+  --line: rgba(233, 238, 243, 0.16);
+  --line-strong: rgba(233, 238, 243, 0.28);
+
+  --blue: #3d9bff;
+  --blue-deep: #6bb4ff;
+  --blue-soft: #14283c;
+  --green: #5fd07f;
+  --green-soft: #12291b;
+  --orange: #f0a95c;
+  --orange-soft: #301f0f;
+  --red: #ff8a8f;
+  --red-soft: #331619;
+
+  --shadow-float: 0 22px 55px rgba(0, 0, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.4);
+  --shadow-lift: 0 8px 24px rgba(0, 0, 0, 0.45);
+
+  /* The accent is light here, so anything sitting on it needs dark ink — white
+     on #6bb4ff is 2.19:1. This covers the primary button and the skip link. */
+  --on-accent: #08131f;
+  --accent-pressed: #82c1ff;
+  --code-ink: #d4d8dc;
+  --code-bg: #12181d;
+  --cta-ink: #f5f6f7;
+  --cta-ink-soft: rgba(245, 246, 247, 0.7);
+  --cta-bg: #05080a;
+  --cta-line: rgba(245, 246, 247, 0.32);
+  --selection-bg: #1d3a5c;
+  --focus-ring: rgba(107, 180, 255, 0.45);
+  --chip-blue-line: rgba(107, 180, 255, 0.28);
+  --chip-green-line: rgba(95, 208, 127, 0.28);
+  --chip-orange-line: rgba(240, 169, 92, 0.28);
+  --chip-red-line: rgba(255, 138, 143, 0.28);
+  --particle: 107, 180, 255;
+}
+
+/* The Codex and OpenCode marks declare fill="currentColor", but an <img> has no
+   inheriting context, so they render black and vanish here. Inverting is safe
+   because both are single-shape glyphs — the marks with real brand colours are
+   not flagged and stay untouched. See AgentMark.astro. */
+.theme-dark .agent-mark-wrap img[data-monochrome] { filter: invert(1); }
+
+/* System preference is not read here on purpose. The inline script in
+   BaseLayout resolves stored choice + system preference into a single
+   .theme-dark class, so there is one source of truth instead of a CSS query and
+   a script that can disagree mid-session. */
+
 @media (prefers-reduced-motion: reduce) {
-  *, *::before, *::after { scroll-behavior: auto !important; animation-duration: .01ms !important; animation-iteration-count: 1 !important; transition-duration: .01ms !important; }
+  *, *::before, *::after { scroll-behavior: auto !important; animation: none !important; transition: none !important; }
 }
 
-:focus-visible { outline: 3px solid rgba(36,103,242,.33); outline-offset: 3px; }
+/* Translucent chrome has to become a real surface when the reader has asked for
+   less transparency, and gain a defined edge when they ask for more contrast. */
+@media (prefers-reduced-transparency: reduce) {
+  .site-header { background: var(--surface); backdrop-filter: none; }
+}
+
+@media (prefers-contrast: more) {
+  :root { --line: rgba(60, 60, 67, 0.5); --line-strong: rgba(60, 60, 67, 0.7); --ink-soft: #4a4a4f; --ink-faint: #4a4a4f; }
+  .site-header { background: var(--surface); backdrop-filter: none; }
+  .chip { border-color: var(--line-strong); }
+}
+
+:focus-visible { outline: 3px solid var(--focus-ring); outline-offset: 3px; }
+
+/* Homepage activation entry refinements. */
+.section-actions { margin-top: 28px; }
+.cta-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 10px; }
+@media (max-width: 680px) {
+  .cta-actions { margin-top: 28px; justify-content: flex-start; }
+}
diff --git a/staticcheck.conf b/staticcheck.conf
new file mode 100644
index 00000000..5ef2ff2f
--- /dev/null
+++ b/staticcheck.conf
@@ -0,0 +1,6 @@
+# ST1005 requires lowercase, unpunctuated error strings. OneAgent's error
+# messages are user-facing product copy shown in the wizard and printed by the
+# CLI, and they must stay byte-identical to the established public messages
+# during the Wails migration. Rewriting them to satisfy a Go style convention
+# would change what users read, so the check is off for this module.
+checks = ["all", "-ST1005"]
diff --git a/tests/existing_config_test.sh b/tests/existing_config_test.sh
deleted file mode 100755
index 8c2bdf33..00000000
--- a/tests/existing_config_test.sh
+++ /dev/null
@@ -1,153 +0,0 @@
-#!/usr/bin/env bash
-# Detection against configuration OneAgent did not write.
-#
-# Every cleanroom starts from an empty HOME, so the case that matters most for a
-# tool meant to manage Agents over time never appeared in any of them: a machine
-# that already has configuration on it. status_payload used to report such a
-# machine as configured=True with provider, model and baseUrl all null -- the
-# file was seen but never read.
-#
-# Pure file operations, no network and no package manager, so both cleanrooms and
-# ordinary CI can run it.
-set -euo pipefail
-
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-PYTHON_BIN="${ONEAGENT_PYTHON:-python3.12}"
-HOME_DIR="$(mktemp -d "${TMPDIR:-/tmp}/oneagent-existing-config.XXXXXX")"
-SENTINEL="sk-existing-config-must-not-surface"
-
-cleanup() { rm -rf "$HOME_DIR"; }
-trap cleanup EXIT INT TERM
-
-fail() { echo "FAIL: $*" >&2; exit 1; }
-
-mkdir -p \
-  "$HOME_DIR/.codex" \
-  "$HOME_DIR/.claude" \
-  "$HOME_DIR/.config/opencode" \
-  "$HOME_DIR/.config/kilo" \
-  "$HOME_DIR/.oneagent"
-
-# 1. Hand-written Codex config pointing at a third party, with a comment and an
-#    unrelated table the user cares about.
-cat > "$HOME_DIR/.codex/config.toml" <<EOF
-# my own notes
-model_provider = "vendor"
-model = "gpt-5-mini"
-
-[model_providers.vendor]
-base_url = "https://api.other-vendor.com/v1"
-env_key = "VENDOR_KEY"
-
-[tui]
-theme = "dark"
-EOF
-
-# 2. Claude Code configured by another tool: endpoint and credential present,
-#    but not the full set our adapter writes.
-cat > "$HOME_DIR/.claude/settings.json" <<EOF
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "https://api.third-party.com",
-    "ANTHROPIC_AUTH_TOKEN": "$SENTINEL"
-  },
-  "theme": "dark"
-}
-EOF
-
-# 3. OpenCode with extra user fields that must survive a later write.
-cat > "$HOME_DIR/.config/opencode/opencode.jsonc" <<EOF
-{
-  "provider": {
-    "mine": { "options": { "baseURL": "https://mine.example/v1", "apiKey": "$SENTINEL" } }
-  },
-  "model": "mine/local-llm",
-  "keybinds": { "leader": "ctrl+x" }
-}
-EOF
-
-# 4. A broken file: must be reported, must not take the status request down.
-printf '{"provider": broken' > "$HOME_DIR/.config/kilo/kilo.jsonc"
-
-# 5. Aider script written by hand.
-cat > "$HOME_DIR/.oneagent/aider.env" <<EOF
-export OPENAI_API_BASE='https://hand-written.example/v1'
-export OPENAI_API_KEY='$SENTINEL'
-EOF
-
-cd "$ROOT_DIR"
-"$PYTHON_BIN" - "$HOME_DIR" "$SENTINEL" <<'PY'
-import json
-import sys
-from pathlib import Path
-
-sys.path.insert(0, ".")
-from oneagent.installer import InstallOptions, Runtime, install_many, status_payload
-
-home, sentinel = Path(sys.argv[1]), sys.argv[2]
-runtime = Runtime.create(home=home)
-payload = status_payload(runtime)
-problems = []
-
-expected = {
-    "codex": ("https://api.other-vendor.com/v1", "gpt-5-mini"),
-    "claude-code": ("https://api.third-party.com", ""),
-    "opencode": ("https://mine.example/v1", "local-llm"),
-    "aider": ("https://hand-written.example/v1", ""),
-}
-for agent_id, (base_url, model) in expected.items():
-    detected = payload["agents"][agent_id]["detected"]
-    if detected is None:
-        problems.append(f"{agent_id}: nothing detected")
-        continue
-    if detected["baseUrl"] != base_url:
-        problems.append(f"{agent_id}: baseUrl {detected['baseUrl']!r} != {base_url!r}")
-    if model and detected["model"] != model:
-        problems.append(f"{agent_id}: model {detected['model']!r} != {model!r}")
-    if detected["managedByOneAgent"]:
-        problems.append(f"{agent_id}: reported as OneAgent-managed, but we did not write it")
-    print(f"  {agent_id:12} {detected['baseUrl']}  {detected['model'] or '-'}")
-
-# The binding is empty: this is exactly the state that used to render as
-# "not configured" while a live configuration sat on disk.
-if payload["agents"]["codex"]["provider"] is not None:
-    problems.append("codex: a binding exists, so this is not the external-config case")
-
-broken = payload["agents"]["kilo-cli"]["detected"]
-if not broken or not broken["unreadable"]:
-    problems.append("kilo-cli: a broken config was not reported as unreadable")
-else:
-    print(f"  {'kilo-cli':12} unreadable: {broken['unreadable'][:48]}")
-
-if sentinel in json.dumps(payload, ensure_ascii=False):
-    problems.append("a credential from an existing config reached the status payload")
-
-# Writing over an existing config must keep the fields the user owns.
-install_many(
-    InstallOptions(
-        agents=["opencode"],
-        provider="ppio",
-        api_key="K-OVERWRITE",
-        model="new-model",
-        configure=True,
-        skip_test=True,
-        home=home,
-    ),
-    runtime,
-)
-after = json.loads((home / ".config" / "opencode" / "opencode.jsonc").read_text(encoding="utf-8"))
-if after.get("keybinds", {}).get("leader") != "ctrl+x":
-    problems.append("writing the config dropped a field the user owns")
-if "mine" not in after.get("provider", {}):
-    problems.append("writing the config dropped the user's own provider entry")
-detected = status_payload(runtime)["agents"]["opencode"]["detected"]
-if not detected["managedByOneAgent"]:
-    problems.append("after our write, the config is not reported as OneAgent-managed")
-print(f"  {'opencode':12} after write: {detected['baseUrl']}  managed={detected['managedByOneAgent']}")
-
-if problems:
-    print("\n".join(f"FAIL: {problem}" for problem in problems))
-    raise SystemExit(1)
-PY
-
-echo "Existing-configuration detection passed."
diff --git a/tests/gui_smoke_test.py b/tests/gui_smoke_test.py
deleted file mode 100755
index 2a44a45a..00000000
--- a/tests/gui_smoke_test.py
+++ /dev/null
@@ -1,318 +0,0 @@
-#!/usr/bin/env python3
-import json
-import os
-import socket
-import subprocess
-import sys
-import tempfile
-import threading
-import time
-import http.cookiejar
-from http.server import BaseHTTPRequestHandler, HTTPServer
-from pathlib import Path
-from urllib.error import HTTPError
-from urllib.request import HTTPCookieProcessor, Request, build_opener
-
-
-ROOT = Path(__file__).resolve().parents[1]
-if str(ROOT) not in sys.path:
-    sys.path.insert(0, str(ROOT))
-
-from tests.support import LocalHTTPServer  # noqa: E402
-
-GUI = ROOT / "scripts" / "gui.py"
-CLIENT = build_opener(HTTPCookieProcessor(http.cookiejar.CookieJar()))
-ORIGIN = ""
-
-
-def fail(message):
-    raise AssertionError(message)
-
-
-def free_port():
-    with socket.socket() as sock:
-        sock.bind(("127.0.0.1", 0))
-        return sock.getsockname()[1]
-
-
-def request_json(url, payload=None):
-    if payload is None:
-        req = Request(url)
-    else:
-        data = json.dumps(payload).encode()
-        req = Request(
-            url,
-            data=data,
-            headers={"Content-Type": "application/json", "Origin": ORIGIN},
-            method="POST",
-        )
-    try:
-        with CLIENT.open(req, timeout=5) as res:
-            return res.status, json.loads(res.read().decode())
-    except HTTPError as exc:
-        try:
-            return exc.code, json.loads(exc.read().decode())
-        finally:
-            exc.close()
-
-
-def bootstrap_client(base_url):
-    global CLIENT, ORIGIN
-    ORIGIN = base_url
-    CLIENT = build_opener(HTTPCookieProcessor(http.cookiejar.CookieJar()))
-    try:
-        with CLIENT.open(base_url + "/", timeout=5) as response:
-            response.read()
-    except HTTPError as exc:
-        try:
-            exc.read()
-        finally:
-            exc.close()
-
-
-def wait_for_server(base_url):
-    for _ in range(50):
-        try:
-            status, _ = request_json(base_url + "/api/status")
-            if status == 200:
-                return
-        except Exception:
-            time.sleep(0.1)
-    fail("GUI server did not start")
-
-
-class MockModelHandler(BaseHTTPRequestHandler):
-    status_code = 200
-    models_status_code = 200
-
-    def log_message(self, *_):
-        return
-
-    def do_GET(self):
-        self.send_response(self.models_status_code)
-        self.send_header("Content-Type", "application/json")
-        self.end_headers()
-        if self.models_status_code == 200:
-            self.wfile.write(b'{"data":[{"id":"model-a"},{"id":"model-b"}]}')
-        else:
-            self.wfile.write(b'{"error":"mock"}')
-
-    def do_POST(self):
-        self.send_response(self.status_code)
-        self.send_header("Content-Type", "application/json")
-        self.end_headers()
-        self.wfile.write(b'{"ok":true}')
-
-
-def start_model_server(status_code, models_status_code=200):
-    server = LocalHTTPServer(("127.0.0.1", 0), MockModelHandler)
-    server.RequestHandlerClass.status_code = status_code
-    server.RequestHandlerClass.models_status_code = models_status_code
-    thread = threading.Thread(target=server.serve_forever, daemon=True)
-    thread.start()
-    return server, f"http://127.0.0.1:{server.server_port}/openai"
-
-
-def write_executable(path, text):
-    path.write_text(text)
-    path.chmod(0o755)
-
-
-def main():
-    if not GUI.exists():
-        fail("scripts/gui.py is missing")
-
-    with tempfile.TemporaryDirectory() as tmpdir:
-        tmp = Path(tmpdir)
-        home = tmp / "home"
-        fakebin = tmp / "bin"
-        home.mkdir()
-        fakebin.mkdir()
-
-        npm_log = tmp / "npm.log"
-        uv_log = tmp / "uv.log"
-        write_executable(fakebin / "codex", "#!/usr/bin/env bash\necho fake codex\n")
-        write_executable(fakebin / "claude", "#!/usr/bin/env bash\necho fake claude\n")
-        write_executable(fakebin / "opencode", "#!/usr/bin/env bash\necho fake opencode\n")
-        write_executable(fakebin / "kilo", "#!/usr/bin/env bash\necho fake kilo\n")
-        write_executable(fakebin / "aider", "#!/usr/bin/env bash\necho fake aider\n")
-        write_executable(fakebin / "cursor", "#!/usr/bin/env bash\necho fake cursor\n")
-        write_executable(fakebin / "npm", f"#!/usr/bin/env bash\necho \"$@\" >> {npm_log}\n")
-        write_executable(fakebin / "uv", f"#!/usr/bin/env bash\necho \"$@\" >> {uv_log}\n")
-        write_executable(fakebin / "python3.12", "#!/usr/bin/env bash\necho Python 3.12.0\n")
-
-        env = os.environ.copy()
-        env["HOME"] = str(home)
-        env["PATH"] = f"{fakebin}:/usr/bin:/bin"
-        env["PYTHONUNBUFFERED"] = "1"
-
-        port = free_port()
-        proc = subprocess.Popen(
-            [sys.executable, str(GUI), "--port", str(port), "--no-open"],
-            cwd=str(ROOT),
-            env=env,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            text=True,
-        )
-        base_url = f"http://127.0.0.1:{port}"
-        try:
-            wait_for_server(base_url)
-            bootstrap_client(base_url)
-
-            status, data = request_json(base_url + "/api/status")
-            assert status == 200
-            assert data["agents"]["codex"]["installed"] is True
-            assert data["agents"]["claude-code"]["installed"] is True
-            assert data["agents"]["opencode"]["installed"] is True
-            assert data["agents"]["kilo-cli"]["installed"] is True
-            assert data["agents"]["aider"]["installed"] is True
-            assert data["agents"]["openclaw"]["guideOnly"] is True
-            assert "catalog" in data
-            assert {"auto", "gateway", "platform", "ide"} <= {group["id"] for group in data["groups"]}
-            assert data["providers"]["ppio"]["base_url"] == "https://api.ppio.com/openai"
-            assert data["providers"]["novita"]["base_url"] == "https://api.novita.ai/openai"
-
-            model_server, model_base = start_model_server(200)
-            try:
-                status, data = request_json(base_url + "/api/probe", {
-                    "provider": "custom",
-                    "api_base_url": model_base,
-                    "api_key": "sk-test",
-                    "model": "gpt-test",
-                })
-                assert status == 200
-                assert data["ok"] is True
-                status, data = request_json(base_url + "/api/models", {
-                    "provider": "custom",
-                    "api_base_url": model_base,
-                    "api_key": "sk-test",
-                })
-                assert status == 200
-                assert data["models"] == ["model-a", "model-b"]
-            finally:
-                model_server.shutdown()
-
-            status, data = request_json(base_url + "/api/install", {
-                "agents": ["codex", "claude-code"],
-                "provider": "ppio",
-                "api_key": "sk-test",
-                "model": "gpt-test",
-                "configure": True,
-                "install_agent": False,
-                "skip_test": True,
-            })
-            assert status == 200
-            assert data["ok"] is True
-            assert "sk-test" not in data["log"]
-            assert (home / ".codex" / "config.toml").exists()
-            assert (home / ".claude" / "settings.json").exists()
-            assert {item["agent"] for item in data["results"]} == {"codex", "claude-code"}
-
-            status, data = request_json(base_url + "/api/install", {
-                "agents": ["opencode", "kilo-cli", "aider", "openclaw", "cursor"],
-                "provider": "ppio",
-                "api_key": "sk-test",
-                "model": "gpt-test",
-                "configure": True,
-                "install_agent": False,
-                "skip_test": True,
-            })
-            assert status == 200
-            assert data["ok"] is True
-            assert "sk-test" not in json.dumps(data)
-            by_agent = {item["agent"]: item["status"] for item in data["results"]}
-            assert by_agent["opencode"] == "configured"
-            assert by_agent["kilo-cli"] == "configured"
-            assert by_agent["aider"] == "configured"
-            assert by_agent["openclaw"] == "guide-only"
-            assert by_agent["cursor"] == "guide-only"
-
-            opencode_config = json.loads((home / ".config" / "opencode" / "opencode.jsonc").read_text())
-            kilo_config = json.loads((home / ".config" / "kilo" / "kilo.jsonc").read_text())
-            assert opencode_config["provider"]["oneagent"]["npm"] == "@ai-sdk/openai-compatible"
-            assert opencode_config["provider"]["oneagent"]["options"]["baseURL"] == "https://api.ppio.com/openai/v1"
-            # Each Agent reads its own variable so two of them can point at
-            # different providers in one shell.
-            assert opencode_config["provider"]["oneagent"]["options"]["apiKey"] == "{env:ONEAGENT_API_KEY_OPENCODE}"
-            assert kilo_config["provider"]["oneagent"]["options"]["apiKey"] == "{env:ONEAGENT_API_KEY_KILO_CLI}"
-            assert kilo_config["provider"]["oneagent"]["options"]["baseURL"] == "https://api.ppio.com/openai/v1"
-            for agent in ("codex", "opencode", "kilo-cli"):
-                assert (home / ".oneagent" / "agents" / f"{agent}.env").exists()
-            assert (home / ".oneagent" / "aider.env").read_text().count("sk-test") == 1
-            assert not (home / ".openclaw").exists()
-            assert not (home / ".cursor").exists()
-
-            status, data = request_json(base_url + "/api/install", {
-                "agents": ["openclaw"],
-                "configure": True,
-                "install_agent": True,
-            })
-            assert status == 200
-            assert data["ok"] is True
-            assert data["results"][0]["status"] == "guide-only"
-            assert not (home / ".openclaw").exists()
-
-            status, data = request_json(base_url + "/api/install", {
-                "agents": ["codex"],
-                "configure": False,
-                "install_agent": False,
-            })
-            assert status == 200
-            assert data["ok"] is True
-            assert "Model configuration skipped" in data["log"]
-
-            (fakebin / "codex").unlink()
-            status, data = request_json(base_url + "/api/install", {
-                "agents": ["codex", "claude-code"],
-                "provider": "ppio",
-                "api_key": "sk-test",
-                "model": "gpt-test",
-                "configure": True,
-                "install_agent": True,
-                "skip_test": True,
-            })
-            assert status == 200
-            npm_calls = npm_log.read_text()
-            assert "@openai/codex" in npm_calls
-
-            (fakebin / "claude").unlink()
-            status, data = request_json(base_url + "/api/install", {
-                "agents": ["claude-code"],
-                "configure": False,
-                "install_agent": True,
-            })
-            assert status == 200
-            assert "@anthropic-ai/claude-code" in npm_log.read_text()
-
-            (fakebin / "opencode").unlink()
-            (fakebin / "kilo").unlink()
-            (fakebin / "aider").unlink()
-            status, data = request_json(base_url + "/api/install", {
-                "agents": ["opencode", "kilo-cli", "aider", "openclaw"],
-                "provider": "ppio",
-                "api_key": "sk-test",
-                "model": "gpt-test",
-                "configure": True,
-                "install_agent": True,
-                "skip_test": True,
-            })
-            assert status == 200
-            assert "opencode-ai" in npm_log.read_text()
-            assert "@kilocode/cli" in npm_log.read_text()
-            uv_calls = uv_log.read_text()
-            assert "tool install" in uv_calls
-            assert "--no-python-downloads" in uv_calls
-            assert "aider-chat==0.86.2" in uv_calls
-        finally:
-            proc.terminate()
-            try:
-                proc.wait(timeout=5)
-            except subprocess.TimeoutExpired:
-                proc.kill()
-
-    print("gui smoke tests passed")
-
-
-if __name__ == "__main__":
-    main()
diff --git a/tests/install_test.sh b/tests/install_test.sh
deleted file mode 100755
index 12306b69..00000000
--- a/tests/install_test.sh
+++ /dev/null
@@ -1,263 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-INSTALLER="$ROOT_DIR/scripts/install.sh"
-
-fail() {
-  echo "FAIL: $*" >&2
-  exit 1
-}
-
-assert_file_contains() {
-  local file="$1"
-  local expected="$2"
-  grep -Fq "$expected" "$file" || fail "$file missing: $expected"
-}
-
-test_codex_writes_config_and_env() {
-  local tmp
-  tmp="$(mktemp -d)"
-  trap 'rm -rf "$tmp"' RETURN
-
-  HOME="$tmp" "$INSTALLER" \
-    --agent codex \
-    --api-base-url https://models.example.com/v1 \
-    --api-key sk-test \
-    --model gpt-test \
-    --channel test \
-    --skip-test \
-    --no-open >/dev/null
-
-  assert_file_contains "$tmp/.codex/config.toml" 'model_provider = "oneagent"'
-  assert_file_contains "$tmp/.codex/config.toml" 'model = "gpt-test"'
-  assert_file_contains "$tmp/.codex/config.toml" 'base_url = "https://models.example.com/v1"'
-  assert_file_contains "$tmp/.codex/config.toml" 'env_key = "ONEAGENT_API_KEY_CODEX"'
-  assert_file_contains "$tmp/.oneagent/agents/codex.env" "export ONEAGENT_API_KEY_CODEX=sk-test"
-  # The shared file stays for configs written before the per-Agent split.
-  assert_file_contains "$tmp/.oneagent/env" "export ONEAGENT_API_KEY=sk-test"
-}
-
-test_codex_backs_up_existing_config() {
-  local tmp
-  tmp="$(mktemp -d)"
-  trap 'rm -rf "$tmp"' RETURN
-  mkdir -p "$tmp/.codex"
-  echo 'model = "old"' > "$tmp/.codex/config.toml"
-
-  HOME="$tmp" "$INSTALLER" \
-    --agent codex \
-    --api-base-url https://models.example.com/v1 \
-    --api-key sk-test \
-    --skip-test \
-    --no-open >/dev/null
-
-  find "$tmp/.codex" -name 'config.toml.backup-*' | grep -q . || fail "missing Codex backup"
-}
-
-test_ppio_is_default_provider() {
-  local tmp
-  tmp="$(mktemp -d)"
-  trap 'rm -rf "$tmp"' RETURN
-
-  HOME="$tmp" "$INSTALLER" \
-    --agent codex \
-    --api-key sk-test \
-    --model gpt-test \
-    --skip-test \
-    --no-open >/dev/null
-
-  assert_file_contains "$tmp/.codex/config.toml" 'name = "PPIO"'
-  assert_file_contains "$tmp/.codex/config.toml" 'base_url = "https://api.ppio.com/openai"'
-}
-
-test_novita_provider() {
-  local tmp
-  tmp="$(mktemp -d)"
-  trap 'rm -rf "$tmp"' RETURN
-
-  HOME="$tmp" "$INSTALLER" \
-    --agent codex \
-    --provider novita \
-    --api-key sk-test \
-    --model gpt-test \
-    --skip-test \
-    --no-open >/dev/null
-
-  assert_file_contains "$tmp/.codex/config.toml" 'name = "Novita"'
-  assert_file_contains "$tmp/.codex/config.toml" 'base_url = "https://api.novita.ai/openai"'
-}
-
-test_rowita_is_rejected() {
-  local tmp
-  tmp="$(mktemp -d)"
-  trap 'rm -rf "$tmp"' RETURN
-
-  if HOME="$tmp" "$INSTALLER" \
-    --agent codex \
-    --provider rowita \
-    --api-key sk-test \
-    --skip-test \
-    --no-open >/dev/null 2>&1; then
-    fail "rowita provider should be rejected"
-  fi
-}
-
-test_register_url_override_is_documented_in_help() {
-  "$INSTALLER" --help | grep -Fq -- "--register-url URL" || fail "missing --register-url help"
-}
-
-test_check_agent_only_does_not_require_key_or_write_config() {
-  local tmp
-  tmp="$(mktemp -d)"
-  trap 'rm -rf "$tmp"' RETURN
-
-  HOME="$tmp" "$INSTALLER" \
-    --agent codex \
-    --check-agent-only \
-    --no-open >/dev/null
-
-  [ ! -e "$tmp/.codex/config.toml" ] || fail "check-agent-only should not write Codex config"
-  [ ! -e "$tmp/.oneagent/env" ] || fail "check-agent-only should not write env file"
-}
-
-test_readme_does_not_recommend_plaintext_api_key_arg() {
-  if grep -Fq -- "--api-key sk-your-key" "$ROOT_DIR/README.md"; then
-    fail "README should not recommend plaintext --api-key"
-  fi
-}
-
-test_missing_agent_message_points_to_official_install() {
-  local tmp out
-  tmp="$(mktemp -d)"
-  trap 'rm -rf "$tmp"' RETURN
-  mkdir -p "$tmp/bin"
-  ln -s "$(command -v python3)" "$tmp/bin/python3"
-
-  out="$(
-    PATH="$tmp/bin:/usr/bin:/bin" HOME="$tmp" "$INSTALLER" \
-      --agent codex \
-      --api-key sk-test \
-      --skip-test \
-      --no-open
-  )"
-
-  printf "%s" "$out" | grep -Fq "official install:" || fail "missing official install hint"
-}
-
-test_claude_merges_settings_json() {
-  local tmp
-  tmp="$(mktemp -d)"
-  trap 'rm -rf "$tmp"' RETURN
-  mkdir -p "$tmp/.claude"
-  printf '{"permissions":{"allow":["Bash(ls)"]},"env":{"FOO":"bar"}}\n' > "$tmp/.claude/settings.json"
-
-  HOME="$tmp" "$INSTALLER" \
-    --agent claude-code \
-    --api-base-url https://anthropic.example.com \
-    --api-key claude-test \
-    --model sonnet \
-    --skip-test \
-    --no-open >/dev/null
-
-  python3 - "$tmp/.claude/settings.json" <<'PY'
-import json
-import sys
-
-with open(sys.argv[1], encoding="utf-8") as f:
-    data = json.load(f)
-
-assert data["permissions"]["allow"] == ["Bash(ls)"]
-assert data["env"]["FOO"] == "bar"
-assert data["env"]["ANTHROPIC_BASE_URL"] == "https://anthropic.example.com"
-assert data["env"]["ANTHROPIC_AUTH_TOKEN"] == "claude-test"
-assert data["env"]["ANTHROPIC_MODEL"] == "sonnet"
-PY
-}
-
-test_opencode_writes_openai_compatible_config() {
-  local tmp
-  tmp="$(mktemp -d)"
-  trap 'rm -rf "$tmp"' RETURN
-
-  HOME="$tmp" "$INSTALLER" \
-    --agent opencode \
-    --provider ppio \
-    --api-key sk-test \
-    --model gpt-test \
-    --skip-test \
-    --no-open >/dev/null
-
-  python3 - "$tmp/.config/opencode/opencode.jsonc" <<'PY'
-import json
-import sys
-
-with open(sys.argv[1], encoding="utf-8") as f:
-    data = json.load(f)
-
-provider = data["provider"]["oneagent"]
-assert data["model"] == "oneagent/gpt-test"
-assert provider["npm"] == "@ai-sdk/openai-compatible"
-assert provider["options"]["baseURL"] == "https://api.ppio.com/openai/v1"
-assert provider["options"]["apiKey"] == "{env:ONEAGENT_API_KEY_OPENCODE}"
-assert provider["models"]["gpt-test"]["name"] == "gpt-test"
-PY
-}
-
-test_kilo_writes_openai_compatible_config() {
-  local tmp
-  tmp="$(mktemp -d)"
-  trap 'rm -rf "$tmp"' RETURN
-
-  HOME="$tmp" "$INSTALLER" \
-    --agent kilo-cli \
-    --api-base-url https://models.example.com/openai/v1/chat/completions \
-    --api-key sk-test \
-    --model gpt-test \
-    --skip-test \
-    --no-open >/dev/null
-
-  python3 - "$tmp/.config/kilo/kilo.jsonc" <<'PY'
-import json
-import sys
-
-with open(sys.argv[1], encoding="utf-8") as f:
-    data = json.load(f)
-
-assert data["provider"]["oneagent"]["options"]["baseURL"] == "https://models.example.com/openai/v1"
-PY
-}
-
-test_aider_writes_independent_env() {
-  local tmp
-  tmp="$(mktemp -d)"
-  trap 'rm -rf "$tmp"' RETURN
-
-  HOME="$tmp" "$INSTALLER" \
-    --agent aider \
-    --provider novita \
-    --api-key sk-test \
-    --model gpt-test \
-    --skip-test \
-    --no-open >/dev/null
-
-  assert_file_contains "$tmp/.oneagent/aider.env" "export OPENAI_API_BASE=https://api.novita.ai/openai/v1"
-  assert_file_contains "$tmp/.oneagent/aider.env" "export OPENAI_API_KEY=sk-test"
-  [ ! -e "$tmp/.oneagent/env" ] || fail "aider should not write shared env file"
-}
-
-test_codex_writes_config_and_env
-test_codex_backs_up_existing_config
-test_ppio_is_default_provider
-test_novita_provider
-test_rowita_is_rejected
-test_register_url_override_is_documented_in_help
-test_check_agent_only_does_not_require_key_or_write_config
-test_readme_does_not_recommend_plaintext_api_key_arg
-test_missing_agent_message_points_to_official_install
-test_claude_merges_settings_json
-test_opencode_writes_openai_compatible_config
-test_kilo_writes_openai_compatible_config
-test_aider_writes_independent_env
-
-echo "install tests passed"
diff --git a/tests/macos_cleanroom_test.sh b/tests/macos_cleanroom_test.sh
deleted file mode 100755
index dfa0ff77..00000000
--- a/tests/macos_cleanroom_test.sh
+++ /dev/null
@@ -1,305 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-REAL_HOME="${HOME:?HOME is required}"
-PACKAGED_BINARY="${ONEAGENT_PACKAGED_BINARY:-}"
-ARTIFACT_DIR="${ONEAGENT_MACOS_CLEANROOM_ARTIFACTS:-$ROOT_DIR/build/macos-cleanroom}"
-
-if [[ "$(uname -s)" != "Darwin" ]]; then
-  echo "macOS cleanroom requires a real Darwin host." >&2
-  exit 2
-fi
-if [[ -z "$PACKAGED_BINARY" || ! -x "$PACKAGED_BINARY" ]]; then
-  echo "ONEAGENT_PACKAGED_BINARY must point to the native OneAgent executable." >&2
-  exit 2
-fi
-
-PYTHON_BIN="$(command -v python3.12 || true)"
-NODE_BIN="$(command -v node || true)"
-NPM_BIN="$(command -v npm || true)"
-if [[ -z "$PYTHON_BIN" || -z "$NODE_BIN" || -z "$NPM_BIN" ]]; then
-  echo "Python 3.12, Node and npm are required for the macOS cleanroom." >&2
-  exit 2
-fi
-
-CLEAN_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/oneagent-macos-cleanroom.XXXXXX")"
-CLEAN_HOME="$CLEAN_ROOT/home"
-CLEAN_TMP="$CLEAN_ROOT/tmp"
-FAKE_BIN="$CLEAN_ROOT/bin"
-BEFORE_SNAPSHOT="$CLEAN_ROOT/real-home-before.json"
-AFTER_SNAPSHOT="$CLEAN_ROOT/real-home-after.json"
-MOCK_KEY="oneagent-macos-cleanroom-placeholder"
-SERVER_PIDS=()
-
-mkdir -p "$CLEAN_HOME" "$CLEAN_TMP" "$FAKE_BIN" "$ARTIFACT_DIR"
-chmod 0700 "$CLEAN_HOME" "$CLEAN_TMP" "$FAKE_BIN"
-ln -s "$PYTHON_BIN" "$FAKE_BIN/python3.12"
-ln -s "$PYTHON_BIN" "$FAKE_BIN/python3"
-ln -s "$NODE_BIN" "$FAKE_BIN/node"
-ln -s "$NPM_BIN" "$FAKE_BIN/npm"
-printf '%s\n' '#!/bin/bash' 'echo "fake uv must not install a real package" >&2' 'exit 97' > "$FAKE_BIN/uv"
-chmod 0755 "$FAKE_BIN/uv"
-
-CLEAN_PATH="$FAKE_BIN:/usr/bin:/bin:/usr/sbin:/sbin"
-
-rm -rf "$ARTIFACT_DIR"
-mkdir -p "$ARTIFACT_DIR"
-
-snapshot_real_home() {
-  local destination="$1"
-  "$PYTHON_BIN" - "$REAL_HOME" "$destination" <<'PY'
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import stat
-import sys
-from pathlib import Path
-
-home = Path(sys.argv[1])
-destination = Path(sys.argv[2])
-targets = [
-    ".codex/config.toml",
-    ".claude/settings.json",
-    ".config/opencode/opencode.jsonc",
-    ".config/kilo/kilo.jsonc",
-    ".oneagent",
-    ".aider.conf.yml",
-]
-snapshot: dict[str, object] = {}
-
-for relative in targets:
-    target = home / relative
-    if not target.exists() and not target.is_symlink():
-        snapshot[relative] = None
-        continue
-    entries = [target]
-    if target.is_dir():
-        entries.extend(sorted(target.rglob("*")))
-    values = []
-    for entry in entries:
-        info = entry.lstat()
-        item = {
-            "path": str(entry.relative_to(home)),
-            "mode": stat.S_IMODE(info.st_mode),
-            "size": info.st_size,
-        }
-        if entry.is_symlink():
-            item["symlink"] = os.readlink(entry)
-        elif entry.is_file():
-            item["sha256"] = hashlib.sha256(entry.read_bytes()).hexdigest()
-        values.append(item)
-    snapshot[relative] = values
-
-destination.write_text(json.dumps(snapshot, sort_keys=True, indent=2), encoding="utf-8")
-PY
-}
-
-clean_env() {
-  env -i \
-    HOME="$CLEAN_HOME" \
-    USERPROFILE="$CLEAN_HOME" \
-    TMPDIR="$CLEAN_TMP" \
-    TEMP="$CLEAN_TMP" \
-    TMP="$CLEAN_TMP" \
-    PATH="$CLEAN_PATH" \
-    LANG="C" \
-    LC_ALL="C" \
-    ONEAGENT_DISABLE_BROWSER="1" \
-    "$@"
-}
-
-finish() {
-  local status=$?
-  trap - EXIT INT TERM
-  local pid
-  for pid in "${SERVER_PIDS[@]:-}"; do
-    kill "$pid" >/dev/null 2>&1 || true
-    wait "$pid" >/dev/null 2>&1 || true
-  done
-  snapshot_real_home "$AFTER_SNAPSHOT"
-  if ! cmp -s "$BEFORE_SNAPSHOT" "$AFTER_SNAPSHOT"; then
-    echo "macOS cleanroom modified a real user configuration path." >&2
-    cp "$BEFORE_SNAPSHOT" "$ARTIFACT_DIR/real-home-before.json"
-    cp "$AFTER_SNAPSHOT" "$ARTIFACT_DIR/real-home-after.json"
-    status=1
-  fi
-  rm -rf "$CLEAN_ROOT"
-  exit "$status"
-}
-trap finish EXIT INT TERM
-
-assert_mode() {
-  local expected="$1"
-  local path="$2"
-  local actual
-  actual="$(stat -f %Lp "$path")"
-  if [[ "$actual" != "$expected" ]]; then
-    echo "unexpected mode for $path: expected $expected, got $actual" >&2
-    return 1
-  fi
-}
-
-wait_for_url() {
-  local file="$1"
-  local pid="$2"
-  for _ in {1..100}; do
-    if [[ -s "$file" ]]; then
-      head -n 1 "$file"
-      return 0
-    fi
-    if ! kill -0 "$pid" >/dev/null 2>&1; then
-      echo "GUI process exited before publishing its URL." >&2
-      return 1
-    fi
-    sleep 0.1
-  done
-  echo "Timed out waiting for GUI URL." >&2
-  return 1
-}
-
-check_gui() {
-  local label="$1"
-  shift
-  local url_file="$CLEAN_ROOT/$label.url"
-  local log_file="$ARTIFACT_DIR/$label.log"
-  clean_env "$@" > "$url_file" 2> "$log_file" &
-  local pid=$!
-  SERVER_PIDS+=("$pid")
-  local url
-  url="$(wait_for_url "$url_file" "$pid")"
-
-  clean_env "$PYTHON_BIN" - "$url" "$REAL_HOME" <<'PY'
-from __future__ import annotations
-
-import json
-import sys
-from http.cookiejar import CookieJar
-from urllib.error import HTTPError
-from urllib.parse import urljoin
-from urllib.request import HTTPCookieProcessor, Request, build_opener, urlopen
-
-base = sys.argv[1]
-real_home = sys.argv[2]
-opener = build_opener(HTTPCookieProcessor(CookieJar()))
-root = opener.open(base, timeout=5)
-cookie = root.headers.get("Set-Cookie", "")
-assert "HttpOnly" in cookie and "SameSite=Strict" in cookie, cookie
-assert root.headers.get("Content-Security-Policy"), "CSP header is missing"
-
-status = json.load(opener.open(urljoin(base, "api/status"), timeout=5))
-assert status["platform"]["os"] == "macos", status["platform"]
-for path in status["paths"].values():
-    assert not str(path).startswith(real_home), path
-
-payload = json.dumps({}).encode()
-try:
-    opener.open(Request(urljoin(base, "api/models"), data=payload, method="POST", headers={"Content-Type": "application/json"}), timeout=5)
-except HTTPError as exc:
-    assert exc.code == 403
-    assert json.load(exc)["error_code"] == "INVALID_ORIGIN"
-else:
-    raise AssertionError("POST without Origin must be rejected")
-
-origin = base.rstrip("/")
-try:
-    urlopen(Request(urljoin(base, "api/models"), data=payload, method="POST", headers={"Content-Type": "application/json", "Origin": origin}), timeout=5)
-except HTTPError as exc:
-    assert exc.code == 403
-else:
-    raise AssertionError("POST without session cookie must be rejected")
-PY
-
-  kill "$pid"
-  wait "$pid" || true
-}
-
-snapshot_real_home "$BEFORE_SNAPSHOT"
-
-for command_name in codex claude opencode kilo aider; do
-  if clean_env "$PYTHON_BIN" -c 'import shutil, sys; raise SystemExit(0 if shutil.which(sys.argv[1]) else 1)' "$command_name"; then
-    echo "Unexpected preinstalled Agent in macOS cleanroom PATH: $command_name" >&2
-    exit 1
-  fi
-done
-
-clean_env "$PYTHON_BIN" -m unittest \
-  tests.test_core tests.test_cli tests.test_server tests.test_edge_cases \
-  > "$ARTIFACT_DIR/python-contracts.log" 2>&1
-clean_env /bin/bash tests/install_test.sh > "$ARTIFACT_DIR/bash-contracts.log" 2>&1
-# Every stage above starts from an empty HOME, so a machine that already has
-# Agent configuration on it -- the normal case for a tool meant to manage them
-# over time -- was never exercised here.
-clean_env /bin/bash tests/existing_config_test.sh > "$ARTIFACT_DIR/existing-config.log" 2>&1
-clean_env "$PYTHON_BIN" tests/gui_smoke_test.py > "$ARTIFACT_DIR/gui-smoke.log" 2>&1
-
-for agent in codex claude-code opencode kilo-cli aider; do
-  clean_env env ONEAGENT_API_KEY="$MOCK_KEY" /bin/bash scripts/install.sh \
-    --agent "$agent" \
-    --provider custom \
-    --api-base-url http://127.0.0.1:9/openai \
-    --model cleanroom-model \
-    --skip-test \
-    --no-open \
-    --json \
-    --home "$CLEAN_HOME" \
-    > "$ARTIFACT_DIR/configure-$agent.log"
-done
-
-clean_env env ONEAGENT_API_KEY="$MOCK_KEY" /bin/bash scripts/install.sh \
-  --agent codex \
-  --provider custom \
-  --api-base-url http://127.0.0.1:9/openai \
-  --model cleanroom-model \
-  --skip-test \
-  --no-open \
-  --json \
-  --home "$CLEAN_HOME" \
-  > "$ARTIFACT_DIR/configure-codex-backup.log"
-
-for directory in \
-  "$CLEAN_HOME" \
-  "$CLEAN_HOME/.codex" \
-  "$CLEAN_HOME/.claude" \
-  "$CLEAN_HOME/.config/opencode" \
-  "$CLEAN_HOME/.config/kilo" \
-  "$CLEAN_HOME/.oneagent"; do
-  assert_mode 700 "$directory"
-done
-
-for file in \
-  "$CLEAN_HOME/.codex/config.toml" \
-  "$CLEAN_HOME/.claude/settings.json" \
-  "$CLEAN_HOME/.config/opencode/opencode.jsonc" \
-  "$CLEAN_HOME/.config/kilo/kilo.jsonc" \
-  "$CLEAN_HOME/.oneagent/env" \
-  "$CLEAN_HOME/.oneagent/aider.env" \
-  "$CLEAN_HOME/.oneagent/profile.json"; do
-  assert_mode 600 "$file"
-done
-
-backup_count=0
-while IFS= read -r backup; do
-  assert_mode 600 "$backup"
-  backup_count=$((backup_count + 1))
-done < <(find "$CLEAN_HOME" -type f -name '*.backup-*' -print)
-if [[ "$backup_count" -lt 1 ]]; then
-  echo "Expected at least one secured backup file." >&2
-  exit 1
-fi
-
-if grep -Fq "$MOCK_KEY" "$CLEAN_HOME/.oneagent/profile.json"; then
-  echo "Environment profile must not contain the API key." >&2
-  exit 1
-fi
-if grep -R -Fq -- "$MOCK_KEY" "$ARTIFACT_DIR"; then
-  echo "macOS cleanroom logs contain the mock API key." >&2
-  exit 1
-fi
-
-check_gui source-gui "$PYTHON_BIN" scripts/gui.py --port 0 --no-open
-check_gui packaged-gui "$PACKAGED_BINARY" gui --port 0 --no-open
-
-echo "Real macOS cleanroom passed on $(uname -m)."
diff --git a/tests/real_install_test.sh b/tests/real_install_test.sh
deleted file mode 100755
index 6892efe3..00000000
--- a/tests/real_install_test.sh
+++ /dev/null
@@ -1,220 +0,0 @@
-#!/usr/bin/env bash
-# Really installs Codex and Claude Code, which no other suite does.
-#
-# Every other test replaces Runtime.runner, so "the Agent can be installed" was
-# an assumption: nothing verified that the locked version resolves on a registry,
-# that npm puts the executable somewhere PATH can reach, or that the binary
-# reports the version the manifest pinned. Those are the steps that actually
-# fail on a user's machine.
-#
-# Scope is deliberately the two Agents under verification. Isolation follows
-# macos_cleanroom_test.sh: a clean HOME, env -i, and a snapshot of the real HOME
-# before and after so a leak fails the run.
-#
-#   bash tests/real_install_test.sh                 # official registry
-#   ONEAGENT_REGISTRY=npmmirror bash tests/...      # authorised mirror
-set -euo pipefail
-
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-REAL_HOME="${HOME:?HOME is required}"
-REGISTRY="${ONEAGENT_REGISTRY:-}"
-ARTIFACT_DIR="${ONEAGENT_REAL_INSTALL_ARTIFACTS:-$ROOT_DIR/build/real-install}"
-
-PYTHON_BIN="$(command -v python3.12 || true)"
-NODE_BIN="$(command -v node || true)"
-NPM_BIN="$(command -v npm || true)"
-if [[ -z "$PYTHON_BIN" || -z "$NODE_BIN" || -z "$NPM_BIN" ]]; then
-  echo "Python 3.12, Node and npm are required for the real install cleanroom." >&2
-  exit 2
-fi
-
-CLEAN_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/oneagent-real-install.XXXXXX")"
-CLEAN_HOME="$CLEAN_ROOT/home"
-CLEAN_TMP="$CLEAN_ROOT/tmp"
-CLEAN_BIN="$CLEAN_ROOT/bin"
-NPM_PREFIX="$CLEAN_ROOT/npm-prefix"
-BEFORE_SNAPSHOT="$CLEAN_ROOT/real-home-before.json"
-AFTER_SNAPSHOT="$CLEAN_ROOT/real-home-after.json"
-MOCK_KEY="oneagent-real-install-placeholder"
-
-rm -rf "$ARTIFACT_DIR"
-mkdir -p "$CLEAN_HOME" "$CLEAN_TMP" "$CLEAN_BIN" "$NPM_PREFIX" "$ARTIFACT_DIR"
-chmod 0700 "$CLEAN_HOME" "$CLEAN_TMP"
-ln -s "$PYTHON_BIN" "$CLEAN_BIN/python3.12"
-ln -s "$PYTHON_BIN" "$CLEAN_BIN/python3"
-ln -s "$NODE_BIN" "$CLEAN_BIN/node"
-ln -s "$NPM_BIN" "$CLEAN_BIN/npm"
-
-# The prefix comes first so a globally installed Agent on the developer's own
-# machine cannot satisfy an assertion this run is supposed to prove.
-CLEAN_PATH="$NPM_PREFIX/bin:$CLEAN_BIN:/usr/bin:/bin:/usr/sbin:/sbin"
-
-snapshot_real_home() {
-  "$PYTHON_BIN" - "$REAL_HOME" "$1" <<'PY'
-import hashlib, json, sys
-from pathlib import Path
-
-home, destination = Path(sys.argv[1]), Path(sys.argv[2])
-watched = [
-    ".codex/config.toml",
-    ".claude/settings.json",
-    ".config/opencode/opencode.jsonc",
-    ".config/kilo/kilo.jsonc",
-    ".oneagent",
-]
-state = {}
-for relative in watched:
-    path = home / relative
-    if path.is_file():
-        state[relative] = hashlib.sha256(path.read_bytes()).hexdigest()
-    elif path.is_dir():
-        state[relative] = sorted(
-            f"{item.relative_to(path)}:{hashlib.sha256(item.read_bytes()).hexdigest()}"
-            for item in sorted(path.rglob("*"))
-            if item.is_file()
-        )
-    else:
-        state[relative] = None
-destination.write_text(json.dumps(state, indent=2, sort_keys=True), encoding="utf-8")
-PY
-}
-
-clean_env() {
-  env -i \
-    HOME="$CLEAN_HOME" \
-    USERPROFILE="$CLEAN_HOME" \
-    TMPDIR="$CLEAN_TMP" \
-    TEMP="$CLEAN_TMP" \
-    TMP="$CLEAN_TMP" \
-    PATH="$CLEAN_PATH" \
-    LANG="C" \
-    LC_ALL="C" \
-    npm_config_prefix="$NPM_PREFIX" \
-    npm_config_update_notifier="false" \
-    npm_config_fund="false" \
-    npm_config_audit="false" \
-    ONEAGENT_DISABLE_BROWSER="1" \
-    "$@"
-}
-
-finish() {
-  local status=$?
-  trap - EXIT INT TERM
-  snapshot_real_home "$AFTER_SNAPSHOT"
-  if ! cmp -s "$BEFORE_SNAPSHOT" "$AFTER_SNAPSHOT"; then
-    echo "Real install cleanroom modified a real user configuration path." >&2
-    cp "$BEFORE_SNAPSHOT" "$ARTIFACT_DIR/real-home-before.json"
-    cp "$AFTER_SNAPSHOT" "$ARTIFACT_DIR/real-home-after.json"
-    status=1
-  fi
-  rm -rf "$CLEAN_ROOT"
-  exit "$status"
-}
-
-fail() {
-  echo "FAIL: $*" >&2
-  exit 1
-}
-
-snapshot_real_home "$BEFORE_SNAPSHOT"
-trap finish EXIT INT TERM
-
-locked_version() {
-  "$PYTHON_BIN" -c "
-import json,sys
-print(json.load(open('$ROOT_DIR/agents.lock.json'))['agents'][sys.argv[1]]['package']['version'])
-" "$1"
-}
-
-echo "== 起点：两个 Agent 都不存在 =="
-for command_name in codex claude; do
-  if clean_env command -v "$command_name" >/dev/null 2>&1; then
-    fail "$command_name already resolves inside the cleanroom; the run would prove nothing"
-  fi
-done
-for relative in .codex .claude; do
-  [[ -e "$CLEAN_HOME/$relative" ]] && fail "clean HOME already holds $relative"
-done
-echo "  ok"
-
-echo "== 安装锁定版本（registry: ${REGISTRY:-official}）=="
-registry_args=()
-[[ -n "$REGISTRY" ]] && registry_args=(--registry "$REGISTRY")
-clean_env env ONEAGENT_API_KEY="$MOCK_KEY" "$PYTHON_BIN" -m oneagent.cli \
-  --agent codex,claude-code \
-  --install-agent \
-  --locked-version \
-  --check-agent-only \
-  --json \
-  --home "$CLEAN_HOME" \
-  "${registry_args[@]}" \
-  > "$ARTIFACT_DIR/install.json" 2> "$ARTIFACT_DIR/install.err" \
-  || { cat "$ARTIFACT_DIR/install.err" >&2; fail "installation failed"; }
-echo "  ok"
-
-echo "== 环节3：可执行文件落到 PATH =="
-for command_name in codex claude; do
-  resolved="$(clean_env command -v "$command_name" 2>/dev/null || true)"
-  [[ -n "$resolved" ]] || fail "$command_name did not land anywhere on PATH after installing"
-  echo "  $command_name -> $resolved"
-done
-
-echo "== 环节4：版本等于锁定版本 =="
-for agent in codex claude-code; do
-  expected="$(locked_version "$agent")"
-  command_name="codex"; [[ "$agent" == "claude-code" ]] && command_name="claude"
-  reported="$(clean_env "$command_name" --version 2>&1 | head -1)"
-  case "$reported" in
-    *"$expected"*) echo "  $command_name reports $reported (locked $expected)" ;;
-    *) fail "$command_name reports '$reported' but the manifest locks $expected" ;;
-  esac
-done
-
-echo "== OneAgent 自己的检测与锁定版本一致 =="
-clean_env "$PYTHON_BIN" - "$CLEAN_HOME" <<'PY' || fail "status did not report both Agents as installed at the locked version"
-import sys
-from pathlib import Path
-
-sys.path.insert(0, ".")
-from oneagent.installer import Runtime, status_payload
-
-payload = status_payload(Runtime.create(home=Path(sys.argv[1])))
-ok = True
-for agent_id in ("codex", "claude-code"):
-    agent = payload["agents"][agent_id]
-    matched = agent["installed"] and agent["version"] == agent["lockedVersion"]
-    print(f"  {agent_id}: installed={agent['installed']} version={agent['version']} locked={agent['lockedVersion']}")
-    ok = ok and matched
-sys.exit(0 if ok else 1)
-PY
-
-echo "== 配置写入干净 HOME 且权限正确 =="
-clean_env env ONEAGENT_API_KEY="$MOCK_KEY" "$PYTHON_BIN" -m oneagent.cli \
-  --agent codex,claude-code \
-  --provider custom \
-  --api-base-url http://127.0.0.1:9/openai \
-  --model real-install-model \
-  --skip-test \
-  --json \
-  --home "$CLEAN_HOME" \
-  > "$ARTIFACT_DIR/configure.json" 2> "$ARTIFACT_DIR/configure.err" \
-  || { cat "$ARTIFACT_DIR/configure.err" >&2; fail "configuration failed"; }
-
-for file in "$CLEAN_HOME/.codex/config.toml" "$CLEAN_HOME/.claude/settings.json"; do
-  [[ -f "$file" ]] || fail "$file was not written"
-  mode="$(stat -f %Lp "$file" 2>/dev/null || stat -c %a "$file")"
-  [[ "$mode" == "600" ]] || fail "$file has mode $mode, expected 600"
-  echo "  $mode $(basename "$file")"
-done
-
-echo "== 密钥不落入 profile 与日志 =="
-if grep -Fq "$MOCK_KEY" "$CLEAN_HOME/.oneagent/profile.json" 2>/dev/null; then
-  fail "the environment profile contains the API key"
-fi
-if grep -R -Fq -- "$MOCK_KEY" "$ARTIFACT_DIR"; then
-  fail "cleanroom artifacts contain the API key"
-fi
-echo "  ok"
-
-echo
-echo "Real install cleanroom passed on $(uname -s) $(uname -m) (registry: ${REGISTRY:-official})."
diff --git a/tests/support.py b/tests/support.py
deleted file mode 100644
index 11156bb7..00000000
--- a/tests/support.py
+++ /dev/null
@@ -1,28 +0,0 @@
-"""Shared test helpers."""
-
-from __future__ import annotations
-
-import socketserver
-from http.server import BaseHTTPRequestHandler, HTTPServer
-
-
-class LocalHTTPServer(HTTPServer):
-    """HTTPServer that binds without a reverse DNS lookup.
-
-    http.server's server_bind() resolves the bind address through
-    socket.getfqdn(). On a host with no reverse resolver that call blocks until
-    it times out -- roughly 35s on the macOS CI runners -- and it only fills in
-    self.server_name, which no test reads. oneagent.server carries the same
-    override for the product; mock servers need it so the suite is not paying
-    the stall twice per job.
-    """
-
-    def server_bind(self) -> None:
-        socketserver.TCPServer.server_bind(self)
-        host, port = self.server_address[:2]
-        self.server_name = host
-        self.server_port = port
-
-
-def start_local_server(handler: type[BaseHTTPRequestHandler]) -> LocalHTTPServer:
-    return LocalHTTPServer(("127.0.0.1", 0), handler)
diff --git a/tests/test_cli.py b/tests/test_cli.py
deleted file mode 100644
index 1115e597..00000000
--- a/tests/test_cli.py
+++ /dev/null
@@ -1,307 +0,0 @@
-from __future__ import annotations
-
-import json
-import io
-import os
-import subprocess
-import sys
-import tempfile
-import unittest
-from contextlib import redirect_stderr, redirect_stdout
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-
-from oneagent import cli
-from oneagent.errors import OneAgentError
-
-
-ROOT = Path(__file__).resolve().parents[1]
-
-
-class CliContractTests(unittest.TestCase):
-    def run_cli(self, *args: str, env: dict[str, str] | None = None):
-        values = os.environ.copy()
-        values["PYTHONPATH"] = str(ROOT)
-        if env:
-            values.update(env)
-        return subprocess.run(
-            [sys.executable, "-m", "oneagent.cli", *args],
-            cwd=ROOT,
-            env=values,
-            text=True,
-            capture_output=True,
-            timeout=30,
-        )
-
-    def test_json_success_contract(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            result = self.run_cli(
-                "--agent",
-                "openclaw",
-                "--check-agent-only",
-                "--json",
-                "--home",
-                tmp,
-            )
-            self.assertEqual(result.returncode, 0, result.stderr)
-            payload = json.loads(result.stdout)
-            self.assertTrue(payload["ok"])
-            self.assertEqual(payload["results"][0]["status"], "guide-only")
-
-    def call(self, *args: str) -> tuple[int, str, str]:
-        """Invoke cli.run in-process.
-
-        run_cli uses a subprocess, which is the honest end-to-end check but is
-        invisible to coverage. These call the entry point directly so the
-        branches are measured.
-        """
-        out, err = io.StringIO(), io.StringIO()
-        with redirect_stdout(out), redirect_stderr(err):
-            code = cli.run(list(args))
-        return code, out.getvalue(), err.getvalue()
-
-    def test_agent_subcommand_in_process_covers_both_output_paths(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            code, out, _ = self.call("agent", "list", "--home", tmp)
-            self.assertEqual(code, 0)
-            self.assertIn("no Agent", out)
-
-            code, out, _ = self.call(
-                "agent", "set", "codex", "--provider", "ppio", "--model", "m",
-                "--api-key", "K", "--home", tmp,
-            )
-            self.assertEqual(code, 0)
-            self.assertIn("codex -> ppio / m", out)
-            self.assertIn("next:", out)
-            self.assertNotIn("K", out.replace("Key", "").replace("okay", ""))
-
-            code, out, _ = self.call("agent", "list", "--home", tmp)
-            self.assertEqual(code, 0)
-            self.assertIn("ppio", out)
-
-            code, out, _ = self.call("agent", "list", "--json", "--home", tmp)
-            self.assertEqual(json.loads(out)["agents"]["codex"]["model"], "m")
-
-            # Error paths on both the JSON and the plain branch.
-            code, out, _ = self.call(
-                "agent", "set", "cursor", "--api-key", "k", "--model", "m", "--json", "--home", tmp
-            )
-            self.assertEqual(code, 2)
-            self.assertEqual(json.loads(out)["error_code"], "INVALID_REQUEST")
-
-            code, _, err = self.call("agent", "set", "cursor", "--api-key", "k", "--model", "m", "--home", tmp)
-            self.assertEqual(code, 2)
-            self.assertIn("guide-only", err)
-
-    def test_agent_set_reads_the_key_from_the_environment(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            with patch.dict(os.environ, {"ONEAGENT_API_KEY": "FROM-ENV"}):
-                code, _, _ = self.call(
-                    "agent", "set", "codex", "--provider", "ppio", "--model", "m", "--home", tmp
-                )
-            self.assertEqual(code, 0)
-            env = (Path(tmp) / ".oneagent" / "agents" / "codex.env").read_text(encoding="utf-8")
-            self.assertIn("FROM-ENV", env)
-
-    def test_agent_subcommand_lists_and_repoints_each_agent(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            empty = self.run_cli("agent", "list", "--json", "--home", tmp)
-            self.assertEqual(empty.returncode, 0, empty.stderr)
-            self.assertEqual(json.loads(empty.stdout)["agents"], {})
-
-            first = self.run_cli(
-                "agent", "set", "codex", "--provider", "ppio", "--model", "m-a",
-                "--api-key", "K-CODEX", "--json", "--home", tmp,
-            )
-            self.assertEqual(first.returncode, 0, first.stderr)
-            payload = json.loads(first.stdout)
-            self.assertEqual(payload["provider"], "ppio")
-            self.assertTrue(payload["restart"])
-            self.assertNotIn("K-CODEX", first.stdout)
-
-            self.run_cli(
-                "agent", "set", "opencode", "--provider", "novita", "--model", "m-b",
-                "--api-key", "K-OPENCODE", "--json", "--home", tmp,
-            )
-            listed = json.loads(self.run_cli("agent", "list", "--json", "--home", tmp).stdout)["agents"]
-            self.assertEqual(listed["codex"]["provider"], "ppio")
-            self.assertEqual(listed["opencode"]["provider"], "novita")
-
-            # Human-readable output names both Agents and their providers.
-            plain = self.run_cli("agent", "list", "--home", tmp)
-            self.assertIn("codex", plain.stdout)
-            self.assertIn("novita", plain.stdout)
-
-    def test_agent_subcommand_reports_errors_with_stable_exit_codes(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            guide_only = self.run_cli(
-                "agent", "set", "cursor", "--api-key", "k", "--model", "m", "--json", "--home", tmp
-            )
-            self.assertEqual(guide_only.returncode, 2)
-            self.assertEqual(json.loads(guide_only.stdout)["error_code"], "INVALID_REQUEST")
-
-            no_key = self.run_cli("agent", "set", "codex", "--model", "m", "--home", tmp)
-            self.assertEqual(no_key.returncode, 2)
-            self.assertIn("API key", no_key.stderr)
-
-            # The empty listing still prints something on the plain path.
-            plain = self.run_cli("agent", "list", "--home", tmp)
-            self.assertIn("no Agent", plain.stdout)
-
-    def test_agent_subcommand_can_reuse_a_saved_profile_key(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            from oneagent.installer import Runtime, save_profile
-
-            save_profile(
-                Runtime.create(home=Path(tmp), os_id="linux", which=lambda _n: None),
-                profile_id="team",
-                provider="ppio",
-                model="m",
-                agent_ids=["codex"],
-                api_key="STORED",
-            )
-            result = self.run_cli(
-                "agent", "set", "codex", "--provider", "ppio", "--model", "m",
-                "--profile", "team", "--json", "--home", tmp,
-            )
-            self.assertEqual(result.returncode, 0, result.stderr)
-            self.assertNotIn("STORED", result.stdout)
-            env = (Path(tmp) / ".oneagent" / "agents" / "codex.env").read_text(encoding="utf-8")
-            self.assertIn("STORED", env)
-
-    def test_json_invalid_agent_has_stable_exit_code(self):
-        result = self.run_cli("--agent", "unknown", "--check-agent-only", "--json")
-        self.assertEqual(result.returncode, 2)
-        payload = json.loads(result.stdout)
-        self.assertEqual(payload["error_code"], "INVALID_REQUEST")
-        self.assertEqual(payload["status"], 400)
-        self.assertFalse(payload["retryable"])
-
-    def test_latest_and_locked_version_are_mutually_exclusive(self):
-        result = self.run_cli("--check-agent-only", "--latest", "--locked-version", "--json")
-        self.assertEqual(result.returncode, 2)
-        self.assertEqual(json.loads(result.stdout)["error_code"], "INVALID_REQUEST")
-
-
-class CliUnitTests(unittest.TestCase):
-    def test_registration_url_precedence(self):
-        parser = cli.build_parser()
-        args = parser.parse_args(["--provider", "novita", "--register-url", "https://example.test/register"])
-        self.assertEqual(cli._registration_url(args), "https://example.test/register")
-        args.register_url = ""
-        with patch.dict(os.environ, {"ONEAGENT_REGISTER_URL": "https://env.test/register"}):
-            self.assertEqual(cli._registration_url(args), "https://env.test/register")
-        with patch.dict(os.environ, {}, clear=True):
-            self.assertEqual(cli._registration_url(args), "https://novita.ai/")
-            args.provider = "custom"
-            self.assertEqual(cli._registration_url(args), "https://ppio.com/")
-
-    def test_api_key_resolution_modes(self):
-        parser = cli.build_parser()
-        args = parser.parse_args(["--check-agent-only"])
-        self.assertEqual(cli._resolve_api_key(args), "")
-
-        args = parser.parse_args(["--api-key", "argument-key"])
-        with patch.dict(os.environ, {"ONEAGENT_API_KEY": "environment-key"}):
-            self.assertEqual(cli._resolve_api_key(args), "environment-key")
-        with patch.dict(os.environ, {}, clear=True):
-            self.assertEqual(cli._resolve_api_key(args), "argument-key")
-
-        args = parser.parse_args(["--json"])
-        with patch.dict(os.environ, {}, clear=True), patch.object(sys.stdin, "isatty", return_value=False):
-            with self.assertRaises(OneAgentError):
-                cli._resolve_api_key(args)
-
-        args = parser.parse_args(["--provider", "ppio"])
-        stderr = io.StringIO()
-        with (
-            patch.dict(os.environ, {}, clear=True),
-            patch.object(sys.stdin, "isatty", return_value=True),
-            patch("oneagent.cli.webbrowser.open") as browser,
-            patch("oneagent.cli.getpass.getpass", return_value="interactive-key"),
-            redirect_stderr(stderr),
-        ):
-            self.assertEqual(cli._resolve_api_key(args), "interactive-key")
-        browser.assert_called_once_with("https://ppio.com/")
-        self.assertIn("Create or copy", stderr.getvalue())
-
-    def test_resolve_api_key_refuses_without_a_tty(self):
-        parser = cli.build_parser()
-        args = parser.parse_args(["--provider", "ppio"])
-        with patch.dict(os.environ, {}, clear=True), patch.object(sys.stdin, "isatty", return_value=False):
-            with self.assertRaises(OneAgentError) as missing:
-                cli._resolve_api_key(args)
-        self.assertEqual(missing.exception.code, "INVALID_REQUEST")
-        self.assertIn("ONEAGENT_API_KEY", missing.exception.message)
-
-    def test_run_splits_comma_separated_agents(self):
-        result = {"ok": True, "code": 0, "log": "", "next": "", "results": [], "probe": None}
-        with (
-            patch("oneagent.cli.install_many", return_value=result) as many,
-            patch("oneagent.cli.Runtime.create", return_value=MagicMock()),
-        ):
-            stdout = io.StringIO()
-            with redirect_stdout(stdout):
-                self.assertEqual(cli.run(["--agent", "codex, claude-code ", "--api-key", "k", "--json"]), 0)
-        self.assertEqual(many.call_args.args[0].agents, ["codex", "claude-code"])
-
-    def test_run_rejects_an_empty_agent_list(self):
-        stderr = io.StringIO()
-        with patch("oneagent.cli.Runtime.create", return_value=MagicMock()), redirect_stderr(stderr):
-            self.assertEqual(cli.run(["--agent", ",", "--check-agent-only"]), 2)
-        self.assertIn("At least one Agent", stderr.getvalue())
-
-    def test_run_outputs_human_and_json_results(self):
-        result = {"ok": True, "code": 0, "log": "configured", "next": "codex", "results": [], "probe": None}
-        with patch("oneagent.cli.install_many", return_value=result), patch("oneagent.cli.Runtime.create", return_value=MagicMock()):
-            stdout = io.StringIO()
-            with redirect_stdout(stdout):
-                self.assertEqual(cli.run(["--check-agent-only"]), 0)
-            self.assertIn("configured", stdout.getvalue())
-            self.assertIn("[oneagent] next: codex", stdout.getvalue())
-
-            stdout = io.StringIO()
-            with redirect_stdout(stdout):
-                self.assertEqual(cli.run(["--check-agent-only", "--json"]), 0)
-            self.assertTrue(json.loads(stdout.getvalue())["ok"])
-
-    def test_run_maps_expected_and_unexpected_failures(self):
-        with patch("oneagent.cli.install_many", side_effect=OneAgentError("CONFIG_WRITE_FAILED", "secret failed")), patch("oneagent.cli.Runtime.create", return_value=MagicMock()):
-            stderr = io.StringIO()
-            with redirect_stderr(stderr):
-                self.assertEqual(cli.run(["--api-key", "secret", "--skip-test"]), 5)
-            self.assertNotIn("secret failed", stderr.getvalue().replace("[redacted] failed", ""))
-            self.assertIn("[redacted]", stderr.getvalue())
-
-        with patch("oneagent.cli.install_many", side_effect=OneAgentError("INVALID_REQUEST", "bad")), patch("oneagent.cli.Runtime.create", return_value=MagicMock()):
-            stdout = io.StringIO()
-            with redirect_stdout(stdout):
-                self.assertEqual(cli.run(["--api-key", "key", "--json"]), 2)
-            self.assertEqual(json.loads(stdout.getvalue())["error_code"], "INVALID_REQUEST")
-
-        with patch("oneagent.cli.install_many", side_effect=KeyboardInterrupt), patch("oneagent.cli.Runtime.create", return_value=MagicMock()):
-            self.assertEqual(cli.run(["--api-key", "key"]), 130)
-
-        with patch("oneagent.cli.install_many", side_effect=RuntimeError("details")), patch("oneagent.cli.Runtime.create", return_value=MagicMock()):
-            stderr = io.StringIO()
-            with redirect_stderr(stderr):
-                self.assertEqual(cli.run(["--api-key", "key"]), 10)
-            self.assertIn("Unexpected OneAgent failure", stderr.getvalue())
-
-        with (
-            patch("oneagent.cli.install_many", side_effect=RuntimeError("details")),
-            patch("oneagent.cli.Runtime.create", return_value=MagicMock()),
-            patch.dict(os.environ, {"ONEAGENT_DEBUG": "1"}),
-        ):
-            with self.assertRaisesRegex(RuntimeError, "details"):
-                cli.run(["--api-key", "key"])
-
-    def test_main_exits_with_run_code(self):
-        with patch("oneagent.cli.run", return_value=7):
-            with self.assertRaises(SystemExit) as error:
-                cli.main()
-        self.assertEqual(error.exception.code, 7)
-
-
-if __name__ == "__main__":
-    unittest.main()
diff --git a/tests/test_config_discovery.py b/tests/test_config_discovery.py
deleted file mode 100644
index a18da78b..00000000
--- a/tests/test_config_discovery.py
+++ /dev/null
@@ -1,369 +0,0 @@
-"""Reading the configuration a user already had.
-
-status_payload used to report configured=True with provider, model and baseUrl
-all null for a config OneAgent had not written itself: the file was seen but
-never read. The overview therefore said "not configured" while a configuration
-was live, and Apply would silently overwrite it.
-"""
-
-from __future__ import annotations
-
-import json
-import tempfile
-import unittest
-from pathlib import Path
-
-from oneagent.catalog import agent_catalog
-from oneagent.installer import (
-    InstallOptions,
-    Runtime,
-    detect_agent_config,
-    install_many,
-    read_aider_config,
-    read_claude_config,
-    read_codex_config,
-    read_openai_compatible_config,
-    status_payload,
-)
-
-
-class FakeRunner:
-    def __call__(self, args, **_kwargs):
-        import subprocess
-
-        values = [str(item) for item in args]
-        if "--version" in values:
-            return subprocess.CompletedProcess(values, 0, "codex-cli 0.145.0\n", "")
-        if "view" in values and "dist.integrity" in values:
-            name = values[2].rsplit("@", 1)[0]
-            for meta in agent_catalog().values():
-                package = meta.get("package") or {}
-                if package.get("name") == name:
-                    return subprocess.CompletedProcess(values, 0, f"{package.get('integrity','')}\n", "")
-        return subprocess.CompletedProcess(values, 0, "ok\n", "")
-
-
-def runtime_for(home: Path) -> Runtime:
-    return Runtime(
-        home=home,
-        os_id="linux",
-        runner=FakeRunner(),
-        which=lambda name: f"/usr/bin/{name}",
-        env={},
-    )
-
-
-class ReaderTests(unittest.TestCase):
-    """Each reader follows the provider the file selects, not ours."""
-
-    def test_codex_reads_the_provider_the_file_actually_selects(self):
-        detected = read_codex_config(
-            'model_provider = "someone-else"\n'
-            'model = "gpt-5-mini"\n'
-            "[model_providers.someone-else]\n"
-            'base_url = "https://api.other-vendor.com/v1"\n'
-            'env_key = "OTHER_KEY"\n'
-        )
-        self.assertEqual(detected["baseUrl"], "https://api.other-vendor.com/v1")
-        self.assertEqual(detected["model"], "gpt-5-mini")
-        self.assertFalse(detected["managedByOneAgent"])
-
-    def test_codex_ignores_our_table_when_the_file_selects_another(self):
-        # Reading [model_providers.oneagent] unconditionally would report a
-        # configuration the Agent is not using.
-        detected = read_codex_config(
-            'model_provider = "vendor"\n'
-            'model = "m"\n'
-            "[model_providers.vendor]\n"
-            'base_url = "https://vendor.example/v1"\n'
-            "[model_providers.oneagent]\n"
-            'base_url = "https://ours.example/v1"\n'
-        )
-        self.assertEqual(detected["baseUrl"], "https://vendor.example/v1")
-        # Our table is present, so the file has been through OneAgent...
-        self.assertTrue(detected["managedByOneAgent"])
-
-    def test_claude_requires_every_declared_variable_to_count_as_managed(self):
-        declared = agent_catalog()["claude-code"]["env_vars"]
-        partial = read_claude_config(json.dumps({"env": {declared["base_url"]: "https://x.example"}}))
-        self.assertEqual(partial["baseUrl"], "https://x.example")
-        self.assertFalse(partial["managedByOneAgent"])
-
-        full = read_claude_config(json.dumps({"env": {name: "v" for name in declared.values()}}))
-        self.assertTrue(full["managedByOneAgent"])
-
-    def test_openai_compatible_strips_the_provider_prefix_from_the_model(self):
-        detected = read_openai_compatible_config(
-            json.dumps(
-                {
-                    "provider": {"mine": {"options": {"baseURL": "https://mine.example/v1"}}},
-                    "model": "mine/local-llm",
-                }
-            )
-        )
-        self.assertEqual(detected["baseUrl"], "https://mine.example/v1")
-        self.assertEqual(detected["model"], "local-llm")
-
-    def test_jsonc_comments_are_named_as_such_rather_than_broken_json(self):
-        detected = read_openai_compatible_config('{\n  // a comment\n  "model": "x/y"\n}')
-        self.assertIn("JSONC", detected["unreadable"])
-
-    def test_aider_is_parsed_line_by_line_and_never_executed(self):
-        # The file holds the key, and it is user-editable; executing it would
-        # both leak the credential and run arbitrary shell.
-        detected = read_aider_config(
-            "export OPENAI_API_BASE='https://hand.example/v1'\n"
-            "export OPENAI_API_KEY='sk-must-not-be-read'\n"
-        )
-        self.assertEqual(detected["baseUrl"], "https://hand.example/v1")
-        self.assertNotIn("sk-must-not-be-read", json.dumps(detected))
-
-    def test_aider_never_claims_to_know_who_wrote_its_script(self):
-        # A hand-written script and ours are the same two exports, so there is no
-        # marker to tell them apart. Reporting either as managed would be a guess.
-        ours = read_aider_config(
-            "export OPENAI_API_BASE='https://a.example/v1'\nexport OPENAI_API_KEY='k'\n"
-        )
-        theirs = read_aider_config("export OPENAI_API_BASE='https://a.example/v1'\n")
-        self.assertFalse(ours["managedByOneAgent"])
-        self.assertFalse(theirs["managedByOneAgent"])
-
-    def test_powershell_assignments_are_understood_too(self):
-        detected = read_aider_config("$env:OPENAI_API_BASE = 'https://win.example/v1'\n")
-        self.assertEqual(detected["baseUrl"], "https://win.example/v1")
-
-    def test_a_reader_reports_a_reason_instead_of_raising(self):
-        for detected in [
-            read_codex_config("model_provider = \nbroken ["),
-            read_claude_config("{not json"),
-            read_openai_compatible_config("[]"),
-            read_openai_compatible_config("{ not json"),
-            read_claude_config("[]"),
-        ]:
-            self.assertTrue(detected["unreadable"])
-            self.assertEqual(detected["baseUrl"], "")
-
-    def test_wrongly_typed_fields_are_ignored_rather_than_reported_as_values(self):
-        # These files are user-editable, so any field can be the wrong shape. A
-        # non-string endpoint must read as absent, not crash and not stringify.
-        codex = read_codex_config(
-            "model_provider = 1\nmodel = 2\n[model_providers.p]\nbase_url = 3\n"
-        )
-        self.assertEqual(codex["baseUrl"], "")
-        self.assertEqual(codex["model"], "")
-
-        # A selected provider whose table is not a table, and options that are
-        # not an object.
-        self.assertEqual(read_openai_compatible_config(json.dumps({"provider": {"p": "nope"}, "model": "p/m"}))["baseUrl"], "")
-        self.assertEqual(
-            read_openai_compatible_config(json.dumps({"provider": {"p": {"options": []}}, "model": "p/m"}))["baseUrl"],
-            "",
-        )
-        self.assertEqual(
-            read_openai_compatible_config(json.dumps({"provider": {"p": {"options": {"baseURL": 7}}}, "model": "p/m"}))["baseUrl"],
-            "",
-        )
-        # And a model with no provider prefix still reads as a model.
-        self.assertEqual(read_openai_compatible_config(json.dumps({"model": "bare-model"}))["model"], "bare-model")
-        self.assertEqual(read_claude_config(json.dumps({"env": {"ANTHROPIC_BASE_URL": 5}}))["baseUrl"], "")
-        self.assertEqual(read_claude_config(json.dumps({"env": "not-an-object"}))["baseUrl"], "")
-
-    def test_an_aider_script_is_read_whatever_its_quoting(self):
-        detected = read_aider_config('export OPENAI_API_BASE="https://theirs.example/v1"\nexport SOMETHING=1\n')
-        self.assertEqual(detected["baseUrl"], "https://theirs.example/v1")
-        # An unquoted value, and comments, are both fine.
-        self.assertEqual(
-            read_aider_config("# a note\nexport OPENAI_API_BASE=https://bare.example/v1\n")["baseUrl"],
-            "https://bare.example/v1",
-        )
-
-
-class NoCredentialLeavesDiskTests(unittest.TestCase):
-    """The reason readers extract only an endpoint and a model."""
-
-    def test_no_config_format_can_put_its_key_into_the_status_payload(self):
-        secret = "sk-detected-must-never-surface"
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            (home / ".codex").mkdir()
-            (home / ".claude").mkdir()
-            (home / ".config" / "opencode").mkdir(parents=True)
-            (home / ".oneagent").mkdir()
-            # Three of the five formats hold the credential in plain text.
-            (home / ".codex" / "config.toml").write_text(
-                f'model_provider = "p"\nmodel = "m"\n[model_providers.p]\nbase_url = "https://a.example"\napi_key = "{secret}"\n',
-                encoding="utf-8",
-            )
-            (home / ".claude" / "settings.json").write_text(
-                json.dumps({"env": {"ANTHROPIC_BASE_URL": "https://b.example", "ANTHROPIC_AUTH_TOKEN": secret}}),
-                encoding="utf-8",
-            )
-            (home / ".config" / "opencode" / "opencode.jsonc").write_text(
-                json.dumps({"provider": {"p": {"options": {"baseURL": "https://c.example", "apiKey": secret}}}, "model": "p/m"}),
-                encoding="utf-8",
-            )
-            (home / ".oneagent" / "aider.env").write_text(
-                f"export OPENAI_API_BASE='https://d.example'\nexport OPENAI_API_KEY='{secret}'\n",
-                encoding="utf-8",
-            )
-
-            payload = status_payload(runtime_for(home))
-            self.assertNotIn(secret, json.dumps(payload, ensure_ascii=False))
-            # And the endpoints were still read, so this is not passing by
-            # reading nothing at all.
-            self.assertEqual(payload["agents"]["codex"]["detected"]["baseUrl"], "https://a.example")
-            self.assertEqual(payload["agents"]["claude-code"]["detected"]["baseUrl"], "https://b.example")
-            self.assertEqual(payload["agents"]["aider"]["detected"]["baseUrl"], "https://d.example")
-
-    def test_detected_carries_no_field_about_the_credential_at_all(self):
-        # Even a boolean would say whether this machine has a key configured.
-        detected = read_claude_config(json.dumps({"env": {"ANTHROPIC_AUTH_TOKEN": "sk-x"}}))
-        self.assertEqual(set(detected), {"baseUrl", "model", "managedByOneAgent", "unreadable"})
-
-
-class StatusIntegrationTests(unittest.TestCase):
-    def test_a_hand_written_config_is_reported_instead_of_nulls(self):
-        # The defect this work exists for.
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            (home / ".codex").mkdir()
-            (home / ".codex" / "config.toml").write_text(
-                'model_provider = "vendor"\nmodel = "gpt-5-mini"\n'
-                '[model_providers.vendor]\nbase_url = "https://api.other-vendor.com/v1"\n',
-                encoding="utf-8",
-            )
-            agent = status_payload(runtime_for(home))["agents"]["codex"]
-            # The binding is still empty -- OneAgent did not write this.
-            self.assertIsNone(agent["provider"])
-            # But the configuration is no longer invisible.
-            self.assertEqual(agent["detected"]["baseUrl"], "https://api.other-vendor.com/v1")
-            self.assertEqual(agent["detected"]["model"], "gpt-5-mini")
-            self.assertFalse(agent["detected"]["managedByOneAgent"])
-
-    def test_one_broken_config_does_not_take_down_the_whole_status(self):
-        # It used to: a config edited into invalid TOML raised out of
-        # status_payload and blanked the entire UI.
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            (home / ".codex").mkdir()
-            (home / ".claude").mkdir()
-            (home / ".codex" / "config.toml").write_text("model_provider = \n[[[", encoding="utf-8")
-            (home / ".claude" / "settings.json").write_text(
-                json.dumps({"env": {"ANTHROPIC_BASE_URL": "https://fine.example"}}), encoding="utf-8"
-            )
-            payload = status_payload(runtime_for(home))
-            self.assertTrue(payload["agents"]["codex"]["detected"]["unreadable"])
-            # A healthy Agent beside it still reports normally.
-            self.assertEqual(payload["agents"]["claude-code"]["detected"]["baseUrl"], "https://fine.example")
-
-    def test_guide_only_agents_report_nothing_detected(self):
-        # OneAgent never writes their config, so it has nothing to say about it.
-        with tempfile.TemporaryDirectory() as tmp:
-            payload = status_payload(runtime_for(Path(tmp)))
-            for agent_id, meta in agent_catalog().items():
-                if meta.get("config_mode") == "auto":
-                    continue
-                with self.subTest(agent=agent_id):
-                    self.assertIsNone(payload["agents"][agent_id]["detected"])
-
-    def test_what_we_write_is_what_we_read_back(self):
-        # The round trip is the assertion worth having: it holds both directions
-        # to the same contract, so a change to either is caught here.
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            runtime = runtime_for(home)
-            catalog = agent_catalog()
-            auto = [agent for agent, meta in catalog.items() if meta.get("config_mode") == "auto"]
-            install_many(
-                InstallOptions(
-                    agents=auto,
-                    provider="ppio",
-                    api_key="K-ROUNDTRIP",
-                    model="round-trip-model",
-                    configure=True,
-                    skip_test=True,
-                    home=home,
-                    os_id="linux",
-                ),
-                runtime,
-            )
-            for agent_id in auto:
-                with self.subTest(agent=agent_id):
-                    detected = detect_agent_config(runtime, catalog[agent_id])
-                    self.assertIsNotNone(detected)
-                    self.assertIsNone(detected["unreadable"])
-                    self.assertTrue(detected["baseUrl"], f"{agent_id} reports no endpoint")
-                    if agent_id == "aider":
-                        # Its config is a script we own outright, with no marker a
-                        # hand-written equivalent would lack, and the model is a
-                        # launch argument rather than a field.
-                        self.assertFalse(detected["managedByOneAgent"])
-                    else:
-                        self.assertTrue(
-                            detected["managedByOneAgent"],
-                            f"{agent_id} was written by us but does not look managed",
-                        )
-                        self.assertEqual(detected["model"], "round-trip-model")
-
-    def test_an_agent_with_no_reader_says_so_rather_than_guessing(self):
-        # A lock entry can name an adapter before a reader for it exists; the
-        # honest answer is that we cannot read it, not a guessed endpoint.
-        meta = dict(agent_catalog()["codex"])
-        meta["config_adapter"] = "some-future-format"
-        with tempfile.TemporaryDirectory() as tmp:
-            detected = detect_agent_config(runtime_for(Path(tmp)), meta)
-        self.assertIn("解析器", detected["unreadable"])
-        self.assertEqual(detected["baseUrl"], "")
-
-    def test_an_unreadable_file_reports_the_reason_not_the_contents(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            (home / ".codex").mkdir()
-            config = home / ".codex" / "config.toml"
-            config.write_text('model_provider = "p"\n', encoding="utf-8")
-            config.chmod(0o000)
-            try:
-                detected = detect_agent_config(runtime_for(home), agent_catalog()["codex"])
-            finally:
-                config.chmod(0o600)
-        # Skipped when running as root, where the chmod does not deny us.
-        if detected["unreadable"] is None:
-            self.skipTest("file permissions do not restrict this user")
-        self.assertIn("无法读取", detected["unreadable"])
-
-    def test_a_reader_that_throws_cannot_break_the_status_request(self):
-        # The guarantee matters more than any single reader being correct: one
-        # unexpected shape must not blank the whole UI.
-        import oneagent.installer as installer
-
-        def explode(_text: str) -> dict:
-            raise RuntimeError("unexpected shape")
-
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            (home / ".codex").mkdir()
-            (home / ".codex" / "config.toml").write_text('model_provider = "p"\n', encoding="utf-8")
-            original = installer._CONFIG_READERS["codex"]
-            installer._CONFIG_READERS["codex"] = explode
-            try:
-                detected = detect_agent_config(runtime_for(home), agent_catalog()["codex"])
-                payload = status_payload(runtime_for(home))
-            finally:
-                installer._CONFIG_READERS["codex"] = original
-        self.assertEqual(detected["unreadable"], "配置解析失败")
-        self.assertEqual(payload["agents"]["codex"]["detected"]["unreadable"], "配置解析失败")
-
-    def test_an_empty_or_absent_config_is_distinguished(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            catalog = agent_catalog()
-            # Absent: nothing to report.
-            self.assertIsNone(detect_agent_config(runtime_for(home), catalog["codex"]))
-            # Present but empty: worth saying so, since the file exists.
-            (home / ".codex").mkdir()
-            (home / ".codex" / "config.toml").write_text("   \n", encoding="utf-8")
-            self.assertIn("空", detect_agent_config(runtime_for(home), catalog["codex"])["unreadable"])
-
-
-if __name__ == "__main__":
-    unittest.main()
diff --git a/tests/test_core.py b/tests/test_core.py
deleted file mode 100644
index d3de0aa2..00000000
--- a/tests/test_core.py
+++ /dev/null
@@ -1,662 +0,0 @@
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-import tempfile
-import tomllib
-import unittest
-from pathlib import Path
-from unittest.mock import patch
-
-from oneagent.catalog import agent_catalog, load_manifest, resolve_home
-from oneagent.errors import OneAgentError
-from oneagent.installer import (
-    InstallOptions,
-    Runtime,
-    _restart_hint,
-    activate_agent,
-    agent_env_path,
-    agent_env_var,
-    atomic_write,
-    install_many,
-    list_agent_bindings,
-    load_profile,
-    read_agent_binding,
-    read_profile_secret,
-    redact,
-    save_profile,
-    secrets_path,
-    status_payload,
-)
-from oneagent.providers import openai_base_url, validate_base_url
-
-
-class FakeProcessRunner:
-    def __init__(self, *, fail_install_for: str = "") -> None:
-        self.calls: list[list[str]] = []
-        self.fail_install_for = fail_install_for
-
-    def __call__(self, args, **_kwargs):
-        values = [str(item) for item in args]
-        self.calls.append(values)
-        if "--version" in values:
-            return subprocess.CompletedProcess(values, 0, "codex-cli 0.145.0\n", "")
-        if "view" in values and "dist.integrity" in values:
-            # install_locked_agent compares the registry's checksum with the
-            # manifest before installing, so the stand-in has to answer with the
-            # value the manifest holds for whichever package is being asked
-            # about; anything else is treated as a tampered registry.
-            name = values[2].rsplit("@", 1)[0]
-            integrity = ""
-            for meta in agent_catalog().values():
-                package = meta.get("package") or {}
-                if package.get("name") == name:
-                    integrity = str(package.get("integrity", ""))
-                    break
-            return subprocess.CompletedProcess(values, 0, f"{integrity}\n", "")
-        if self.fail_install_for and any(self.fail_install_for in item for item in values):
-            return subprocess.CompletedProcess(values, 9, "", "failed")
-        return subprocess.CompletedProcess(values, 0, "ok\n", "")
-
-
-def fake_which(mapping: dict[str, str]):
-    return lambda command: mapping.get(command)
-
-
-class CatalogPolicyTests(unittest.TestCase):
-    def test_manifest_has_five_locked_auto_agents(self):
-        manifest = load_manifest()
-        automatic = {key: value for key, value in manifest["agents"].items() if value["config_mode"] == "auto"}
-        self.assertEqual(set(automatic), {"codex", "claude-code", "opencode", "kilo-cli", "aider"})
-        expected_adapters = {
-            "codex": "codex",
-            "claude-code": "claude-code",
-            "opencode": "opencode",
-            "kilo-cli": "kilo-cli",
-            "aider": "aider",
-        }
-        for agent_id, meta in automatic.items():
-            package = meta["package"]
-            with self.subTest(agent=agent_id):
-                self.assertRegex(package["version"], r"^\d+\.\d+\.\d+")
-                self.assertIn(package["manager"], {"npm", "uv"})
-                self.assertTrue(package["source"].startswith("https://"))
-                self.assertTrue(package["license"])
-                self.assertTrue(package["license_url"].startswith("https://"))
-                self.assertEqual(set(meta["platforms"]), {"macos", "linux", "windows"})
-                self.assertEqual(meta["config_adapter"], expected_adapters[agent_id])
-
-    def test_guide_agents_have_no_package_install_contract(self):
-        manifest = load_manifest()
-        for agent_id, meta in manifest["agents"].items():
-            if meta["config_mode"] == "guide":
-                with self.subTest(agent=agent_id):
-                    self.assertNotIn("package", meta)
-                    self.assertIsNone(meta.get("config_adapter"))
-                    self.assertTrue(meta["guide"])
-
-
-class PlatformAndSecurityTests(unittest.TestCase):
-    def test_windows_home_prefers_userprofile(self):
-        home = resolve_home({"USERPROFILE": r"C:\Users\测试 用户", "HOME": "/wrong"}, "windows")
-        self.assertEqual(str(home), r"C:\Users\测试 用户")
-
-    def test_custom_url_rejects_credentials_and_control_characters(self):
-        with self.assertRaises(OneAgentError):
-            validate_base_url("https://user:secret@example.com")
-        with self.assertRaises(OneAgentError):
-            validate_base_url("https://example.com/\nheader")
-
-    def test_openai_url_normalizes_full_endpoint(self):
-        self.assertEqual(
-            openai_base_url("https://models.example.com/openai/v1/chat/completions"),
-            "https://models.example.com/openai/v1",
-        )
-
-    def test_install_options_reject_mutually_exclusive_version_modes(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux")
-            with self.assertRaisesRegex(OneAgentError, "cannot be enabled together"):
-                install_many(
-                    InstallOptions(
-                        agents=["codex"],
-                        configure=False,
-                        locked_version=True,
-                        latest=True,
-                    ),
-                    runtime,
-                )
-
-    def test_redaction_removes_all_secret_occurrences(self):
-        self.assertEqual(redact("key=abc abc", ["abc"]), "key=[redacted] [redacted]")
-
-    def test_windows_secret_file_uses_powershell_quoting_and_acl(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runner = FakeProcessRunner()
-            mapping = {"icacls": r"C:\Windows\System32\icacls.exe"}
-            runtime = Runtime.create(
-                home=Path(tmp) / "用户 Home",
-                os_id="windows",
-                runner=runner,
-                which=fake_which(mapping),
-                env={"USERNAME": "tester", "USERPROFILE": tmp},
-            )
-            result = install_many(
-                InstallOptions(
-                    agents=["codex"],
-                    provider="ppio",
-                    api_key="key'quoted",
-                    model="model-a",
-                    configure=True,
-                    skip_test=True,
-                    home=runtime.home,
-                    os_id="windows",
-                ),
-                runtime,
-            )
-            self.assertTrue(result["ok"])
-            env_text = (runtime.home / ".oneagent" / "env.ps1").read_text(encoding="utf-8")
-            self.assertIn("$env:ONEAGENT_API_KEY = 'key''quoted'", env_text)
-            self.assertTrue(any("/reset" in call for call in runner.calls))
-            self.assertTrue(any("/inheritance:r" in call for call in runner.calls))
-            profile = json.loads((runtime.home / ".oneagent" / "profile.json").read_text(encoding="utf-8"))
-            self.assertNotIn("key", json.dumps(profile).lower())
-
-    @unittest.skipIf(os.name == "nt", "Unix mode assertion")
-    def test_unix_secret_files_are_private(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux")
-            secret = Path(tmp) / ".oneagent" / "secret"
-            secret.parent.mkdir()
-            secret.write_text("old-value\n", encoding="utf-8")
-            secret.chmod(0o644)
-            backup = atomic_write(runtime, secret, "value\n", secret=True)
-            self.assertEqual((Path(tmp) / ".oneagent").stat().st_mode & 0o777, 0o700)
-            self.assertEqual(secret.stat().st_mode & 0o777, 0o600)
-            self.assertIsNotNone(backup)
-            self.assertEqual(backup.stat().st_mode & 0o777, 0o600)
-
-    @unittest.skipUnless(os.name == "nt", "Real ACL assertion runs on Windows CI")
-    def test_windows_secret_acl_allows_only_current_user_and_system(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="windows")
-            secret = Path(tmp) / ".oneagent" / "secret.ps1"
-            atomic_write(runtime, secret, "$env:KEY = 'value'\n", secret=True)
-            script = r"""
-$acl = Get-Acl -LiteralPath $env:ONEAGENT_ACL_TEST_PATH
-$current = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
-$identities = @($acl.Access | ForEach-Object {
-  $_.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value
-} | Sort-Object -Unique)
-[pscustomobject]@{
-  current = $current
-  identities = $identities
-  protected = $acl.AreAccessRulesProtected
-} | ConvertTo-Json -Compress
-"""
-            for path in [secret.parent, secret]:
-                env = os.environ.copy()
-                env["ONEAGENT_ACL_TEST_PATH"] = str(path)
-                result = subprocess.run(
-                    ["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", script],
-                    text=True,
-                    capture_output=True,
-                    check=True,
-                    env=env,
-                )
-                acl = json.loads(result.stdout)
-                identities = acl["identities"]
-                if isinstance(identities, str):
-                    identities = [identities]
-                self.assertTrue(acl["protected"])
-                self.assertEqual(set(identities), {acl["current"], "S-1-5-18"})
-
-
-class PerAgentCredentialTests(unittest.TestCase):
-    def _install(self, tmp: str, agents: list[str], *, provider: str, key: str, model: str):
-        runtime = Runtime.create(
-            home=Path(tmp),
-            os_id="linux",
-            runner=FakeProcessRunner(),
-            which=fake_which({"npm": "/fake/npm", "uv": "/fake/uv"}),
-        )
-        return install_many(
-            InstallOptions(
-                agents=agents,
-                provider=provider,
-                api_key=key,
-                model=model,
-                configure=True,
-                skip_test=True,
-                home=Path(tmp),
-            ),
-            runtime,
-        )
-
-    def test_env_var_name_is_derived_per_agent(self):
-        self.assertEqual(agent_env_var("codex"), "ONEAGENT_API_KEY_CODEX")
-        # A hyphen is not legal in a shell variable name.
-        self.assertEqual(agent_env_var("kilo-cli"), "ONEAGENT_API_KEY_KILO_CLI")
-        self.assertEqual(agent_env_var("codex", "API_BASE_URL"), "ONEAGENT_API_BASE_URL_CODEX")
-
-    def test_agent_env_path_rejects_a_traversing_id(self):
-        # The ID names a file holding a plaintext key, so it must stay one path
-        # segment: the same defect that let a tampered profile pointer escape.
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux", which=lambda _n: None)
-            for bad in ("../../evil", "a/b", "..", "/abs", "Codex", ""):
-                with self.subTest(bad=bad):
-                    with self.assertRaises(OneAgentError):
-                        agent_env_path(runtime, bad)
-
-    def test_two_agents_can_target_different_providers_at_once(self):
-        # The point of the split: a single ONEAGENT_API_KEY meant whichever env
-        # file was sourced last decided the credential for every Agent.
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            self._install(tmp, ["codex"], provider="ppio", key="key-for-codex", model="model-a")
-            self._install(tmp, ["opencode"], provider="novita", key="key-for-opencode", model="model-b")
-
-            codex_env = (home / ".oneagent" / "agents" / "codex.env").read_text(encoding="utf-8")
-            opencode_env = (home / ".oneagent" / "agents" / "opencode.env").read_text(encoding="utf-8")
-
-            # Each file carries its own Agent's key under its own variable, and
-            # neither leaks the other's.
-            self.assertIn("ONEAGENT_API_KEY_CODEX=key-for-codex", codex_env)
-            self.assertNotIn("key-for-opencode", codex_env)
-            self.assertIn("ONEAGENT_API_KEY_OPENCODE=key-for-opencode", opencode_env)
-            self.assertNotIn("key-for-codex", opencode_env)
-
-            # And each config reads the variable its own file defines.
-            config = tomllib.loads((home / ".codex" / "config.toml").read_text(encoding="utf-8"))
-            self.assertEqual(config["model_providers"]["oneagent"]["env_key"], "ONEAGENT_API_KEY_CODEX")
-            opencode = json.loads((home / ".config" / "opencode" / "opencode.jsonc").read_text(encoding="utf-8"))
-            self.assertEqual(
-                opencode["provider"]["oneagent"]["options"]["apiKey"],
-                "{env:ONEAGENT_API_KEY_OPENCODE}",
-            )
-
-    def test_next_step_points_at_the_agents_own_env_file(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            result = self._install(tmp, ["codex"], provider="ppio", key="k", model="m")
-        self.assertIn("source ~/.oneagent/agents/codex.env && codex", result["next"])
-
-
-class AgentActivationTests(unittest.TestCase):
-    def _runtime(self, tmp: str) -> Runtime:
-        return Runtime(
-            home=Path(tmp),
-            os_id="linux",
-            runner=FakeProcessRunner(),
-            which=lambda name: f"/usr/bin/{name}",
-            env={},
-        )
-
-    def test_activating_one_agent_leaves_the_others_untouched(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            activate_agent(runtime, "codex", provider="ppio", api_key="K-CODEX", model="m-a")
-            activate_agent(runtime, "opencode", provider="novita", api_key="K-OPENCODE", model="m-b")
-
-            bindings = list_agent_bindings(runtime)
-            self.assertEqual(bindings["codex"]["provider"], "ppio")
-            self.assertEqual(bindings["opencode"]["provider"], "novita")
-
-            # Repointing codex must not disturb opencode's binding or key.
-            activate_agent(runtime, "codex", provider="novita", api_key="K-CODEX-2", model="m-c")
-            bindings = list_agent_bindings(runtime)
-            self.assertEqual(bindings["codex"]["model"], "m-c")
-            self.assertEqual(bindings["opencode"]["model"], "m-b")
-            opencode_env = (Path(tmp) / ".oneagent" / "agents" / "opencode.env").read_text(encoding="utf-8")
-            self.assertIn("K-OPENCODE", opencode_env)
-            self.assertNotIn("K-CODEX", opencode_env)
-
-    def test_activation_never_returns_the_key_and_always_says_how_to_reload(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            result = activate_agent(
-                self._runtime(tmp), "codex", provider="ppio", api_key="SECRET-KEY", model="m"
-            )
-        self.assertNotIn("SECRET-KEY", json.dumps(result))
-        # An Agent reads its config at startup, so "activated" without a reload
-        # instruction reads as a silent failure.
-        self.assertTrue(result["restart"])
-
-    def test_activation_rejects_guide_only_and_unknown_agents(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            for agent_id in ("cursor", "no-such-agent", "../escape"):
-                with self.subTest(agent=agent_id):
-                    with self.assertRaises(OneAgentError):
-                        activate_agent(runtime, agent_id, provider="ppio", api_key="k", model="m")
-            # A missing key is refused before anything is written.
-            with self.assertRaises(OneAgentError):
-                activate_agent(runtime, "codex", provider="ppio", api_key="", model="m")
-            self.assertEqual(list_agent_bindings(runtime), {})
-
-    def test_a_saved_profile_key_can_be_reused_without_repasting(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            save_profile(
-                runtime,
-                profile_id="team-ppio",
-                provider="ppio",
-                model="m",
-                agent_ids=["codex"],
-                api_key="STORED-KEY",
-            )
-            self.assertEqual(read_profile_secret(runtime, "team-ppio"), "STORED-KEY")
-            # Absent profile yields no key rather than an error.
-            self.assertEqual(read_profile_secret(runtime, "missing"), "")
-
-    def test_unreadable_bindings_are_reported_and_skipped_not_raised(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            directory = Path(tmp) / ".oneagent" / "agents"
-            directory.mkdir(parents=True)
-
-            for content, expected in (
-                ("{", "Expecting"),
-                ("[]", "corrupt"),
-                ('{"schema_version":9}', "Unsupported"),
-            ):
-                with self.subTest(content=content):
-                    (directory / "codex.json").write_text(content, encoding="utf-8")
-                    value, error = read_agent_binding(runtime, "codex")
-                    self.assertIsNone(value)
-                    self.assertIn(expected, error or "")
-
-            # A bad file is skipped by the listing rather than failing the whole
-            # status payload, and a filename that is not a legal ID is ignored.
-            (directory / "Bad-Name.json").write_text('{"schema_version":1}', encoding="utf-8")
-            activate_agent(runtime, "opencode", provider="ppio", api_key="k", model="m")
-            self.assertEqual(list(list_agent_bindings(runtime)), ["opencode"])
-
-        with tempfile.TemporaryDirectory() as tmp:
-            # No directory at all is not an error either.
-            self.assertEqual(list_agent_bindings(self._runtime(tmp)), {})
-
-    def test_restart_hint_covers_every_managed_agent(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            for agent_id in ("codex", "claude-code", "opencode", "kilo-cli", "aider"):
-                with self.subTest(agent=agent_id):
-                    result = activate_agent(
-                        runtime, agent_id, provider="ppio", api_key="k", model="m"
-                    )
-                    self.assertTrue(result["restart"])
-        self.assertIn("aider.env", _restart_hint("aider"))
-        # An Agent with no known launch command still gets an instruction.
-        self.assertEqual(_restart_hint("future-agent"), "Restart future-agent")
-
-    def test_reading_a_profile_key_handles_both_shells_and_bad_files(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            save_profile(
-                runtime, profile_id="p1", provider="ppio", model="m",
-                agent_ids=["codex"], api_key="quoted key",
-            )
-            # shlex round-trips a key that needed quoting.
-            self.assertEqual(read_profile_secret(runtime, "p1"), "quoted key")
-
-            # A secret file with no recognisable assignment yields no key.
-            secrets_path(runtime, "p1").write_text("# nothing here\n", encoding="utf-8")
-            self.assertEqual(read_profile_secret(runtime, "p1"), "")
-
-            # An unreadable secret file is a reported failure, not a silent "".
-            # Returning "" there would make activation fail later with a
-            # confusing "API key is required" instead of the real cause.
-            with patch.object(Path, "read_text", side_effect=OSError("denied")):
-                with self.assertRaises(OneAgentError):
-                    read_profile_secret(runtime, "p1")
-
-        with tempfile.TemporaryDirectory() as tmp:
-            windows = Runtime(
-                home=Path(tmp), os_id="windows", runner=FakeProcessRunner(),
-                which=lambda name: f"C:\\{name}.exe", env={"USERNAME": "tester"},
-            )
-            with patch("oneagent.installer._run_acl"):
-                save_profile(
-                    windows, profile_id="p2", provider="ppio", model="m",
-                    agent_ids=["codex"], api_key="it's",
-                )
-                self.assertEqual(read_profile_secret(windows, "p2"), "it's")
-
-    def test_status_reports_each_agent_binding_separately(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            activate_agent(runtime, "codex", provider="ppio", api_key="k1", model="m-a")
-            payload = status_payload(runtime)
-        self.assertEqual(payload["agents"]["codex"]["provider"], "ppio")
-        self.assertEqual(payload["agents"]["codex"]["model"], "m-a")
-        # An Agent never pointed anywhere reports no binding instead of a stale
-        # or borrowed one.
-        self.assertIsNone(payload["agents"]["opencode"]["provider"])
-
-
-class InstallerContractTests(unittest.TestCase):
-    def test_locked_npm_install_uses_manifest_version_without_shell(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runner = FakeProcessRunner()
-            runtime = Runtime.create(
-                home=Path(tmp),
-                os_id="linux",
-                runner=runner,
-                which=fake_which({"npm": "/fake/npm"}),
-            )
-            result = install_many(
-                InstallOptions(
-                    agents=["codex"],
-                    api_key="secret",
-                    model="model-a",
-                    configure=True,
-                    install_agent=True,
-                    locked_version=True,
-                    skip_test=True,
-                    home=Path(tmp),
-                ),
-                runtime,
-            )
-            self.assertTrue(result["ok"])
-            self.assertIn(["/fake/npm", "install", "-g", "@openai/codex@0.145.0"], runner.calls)
-
-    def test_missing_package_manager_is_structured_failure(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux", which=fake_which({}))
-            result = install_many(
-                InstallOptions(
-                    agents=["codex"],
-                    api_key="secret",
-                    install_agent=True,
-                    skip_test=True,
-                    home=Path(tmp),
-                ),
-                runtime,
-            )
-            self.assertFalse(result["ok"])
-            self.assertEqual(result["results"][0]["error_code"], "PREREQUISITE_MISSING")
-            self.assertEqual(result["results"][0]["code"], 3)
-
-    def test_windows_claude_requires_git(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runner = FakeProcessRunner()
-            runtime = Runtime.create(
-                home=Path(tmp),
-                os_id="windows",
-                runner=runner,
-                which=fake_which({"npm": "npm.cmd", "icacls": "icacls.exe"}),
-                env={"USERNAME": "tester", "USERPROFILE": tmp},
-            )
-            result = install_many(
-                InstallOptions(
-                    agents=["claude-code"],
-                    api_key="secret",
-                    install_agent=True,
-                    skip_test=True,
-                    home=Path(tmp),
-                    os_id="windows",
-                ),
-                runtime,
-            )
-            self.assertFalse(result["ok"])
-            self.assertEqual(result["results"][0]["error_code"], "PREREQUISITE_MISSING")
-
-    def test_guide_only_agent_writes_no_private_configuration(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux", which=fake_which({}))
-            result = install_many(
-                InstallOptions(agents=["openclaw"], configure=False, skip_test=True, home=Path(tmp)),
-                runtime,
-            )
-            self.assertTrue(result["ok"])
-            self.assertEqual(result["results"][0]["status"], "guide-only")
-            self.assertFalse((Path(tmp) / ".openclaw").exists())
-
-    def test_partial_failure_does_not_publish_environment_profile(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runner = FakeProcessRunner(fail_install_for="@openai/codex")
-            runtime = Runtime.create(
-                home=Path(tmp),
-                os_id="linux",
-                runner=runner,
-                which=fake_which({"npm": "/fake/npm"}),
-            )
-            result = install_many(
-                InstallOptions(
-                    agents=["codex", "opencode"],
-                    api_key="secret",
-                    install_agent=True,
-                    skip_test=True,
-                    home=Path(tmp),
-                ),
-                runtime,
-            )
-            self.assertFalse(result["ok"])
-            self.assertEqual({item["status"] for item in result["results"]}, {"failed", "configured"})
-            profile, _ = load_profile(runtime)
-            self.assertIsNone(profile)
-
-            runtime.runner = FakeProcessRunner()
-            retry = install_many(
-                InstallOptions(
-                    agents=["codex"],
-                    profile_agents=["codex", "opencode"],
-                    api_key="secret",
-                    install_agent=True,
-                    skip_test=True,
-                    home=Path(tmp),
-                ),
-                runtime,
-            )
-            self.assertTrue(retry["ok"])
-            profile, _ = load_profile(runtime)
-            self.assertEqual(profile["agent_ids"], ["codex", "opencode"])
-
-    def test_api_key_reaches_only_the_designated_secret_files(self):
-        # The README promises the key never lands anywhere but the local secret
-        # configs. The existing check covered two Agents and two files; this
-        # configures every auto Agent and then walks the whole home directory,
-        # so a new config writer that embeds the key cannot slip through.
-        secret = "sentinel-whole-home-key"
-        auto_agents = [
-            agent_id
-            for agent_id, meta in load_manifest()["agents"].items()
-            if meta["config_mode"] == "auto"
-        ]
-        self.assertEqual(len(auto_agents), 5)
-
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            runtime = Runtime.create(home=home, os_id="linux", which=fake_which({}))
-            result = install_many(
-                InstallOptions(
-                    agents=auto_agents,
-                    provider="ppio",
-                    api_key=secret,
-                    model="model-x",
-                    configure=True,
-                    install_agent=False,
-                    skip_test=True,
-                    home=home,
-                ),
-                runtime,
-            )
-            self.assertTrue(result["ok"], result)
-
-            leaked = {
-                path.relative_to(home).as_posix()
-                for path in home.rglob("*")
-                if path.is_file() and secret in path.read_text(encoding="utf-8", errors="ignore")
-            }
-
-            # Only the files that exist to hold credentials may contain it.
-            # Codex, OpenCode and Kilo reference the key indirectly (env_key
-            # and {env:...}), so their own configs must stay clean. Each of
-            # those three now has its own env file so they can point at
-            # different providers at once; .oneagent/env stays as the
-            # compatibility copy for configs written before that split. The
-            # per-profile secret store (ADR-006) holds a copy so profiles can
-            # be re-activated without re-pasting the key.
-            # Claude Code has an env file for the same reason, plus one of its
-            # own: it ignores the credential in its settings.json and starts
-            # unauthenticated unless ANTHROPIC_AUTH_TOKEN is in the environment.
-            self.assertEqual(
-                leaked,
-                {
-                    ".oneagent/env",
-                    ".oneagent/agents/codex.env",
-                    ".oneagent/agents/opencode.env",
-                    ".oneagent/agents/kilo-cli.env",
-                    ".oneagent/agents/claude-code.env",
-                    ".claude/settings.json",
-                    ".oneagent/aider.env",
-                    ".oneagent/secrets/default.env",
-                },
-            )
-
-        # Nothing the caller receives may carry it either.
-        self.assertNotIn(secret, json.dumps(result))
-        self.assertNotIn(secret, result["log"])
-
-    @unittest.skipIf(os.name == "nt", "Unix mode assertion")
-    def test_every_secret_file_is_written_with_owner_only_mode(self):
-        # Split from the leak test so that one keeps running on Windows: the
-        # set of files carrying the key is platform-independent, but chmod is
-        # a no-op on NTFS, where the same guarantee comes from the ACL path.
-        secret = "sentinel-permission-key"
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            runtime = Runtime.create(home=home, os_id="linux", which=fake_which({}))
-            install_many(
-                InstallOptions(
-                    agents=["codex", "claude-code", "aider"],
-                    provider="ppio",
-                    api_key=secret,
-                    model="model-x",
-                    configure=True,
-                    skip_test=True,
-                    home=home,
-                ),
-                runtime,
-            )
-            for relative in (".oneagent/env", ".claude/settings.json", ".oneagent/aider.env"):
-                path = home / relative
-                with self.subTest(path=relative):
-                    self.assertTrue(path.is_file())
-                    self.assertEqual(path.stat().st_mode & 0o777, 0o600)
-                    self.assertEqual(path.parent.stat().st_mode & 0o777, 0o700)
-
-    def test_profile_is_backed_up_and_status_recovers_it(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux", which=fake_which({}))
-            options = InstallOptions(agents=["openclaw"], configure=False, skip_test=True, home=Path(tmp))
-            self.assertTrue(install_many(options, runtime)["ok"])
-            self.assertTrue(install_many(options, runtime)["ok"])
-            status = status_payload(runtime)
-            self.assertEqual(status["apiVersion"], 1)
-            self.assertEqual(status["environment"]["provider"], "existing-account")
-            self.assertTrue(status["backups"]["profile"])
-
-
-if __name__ == "__main__":
-    unittest.main()
diff --git a/tests/test_distribution_data.py b/tests/test_distribution_data.py
deleted file mode 100644
index 063544b7..00000000
--- a/tests/test_distribution_data.py
+++ /dev/null
@@ -1,303 +0,0 @@
-from __future__ import annotations
-
-import hashlib
-import json
-import tempfile
-import unittest
-from pathlib import Path
-
-from scripts.build_release_index import ReleaseIndexError, build_release_index, copy_available_release_assets
-from scripts.build_site_catalog import SiteCatalogError, build_site_catalog
-
-
-def digest(path: Path) -> str:
-    return hashlib.sha256(path.read_bytes()).hexdigest()
-
-
-class ReleaseIndexTests(unittest.TestCase):
-    def write_fixture(self, root: Path, *, artifact_bytes: bytes = b"oneagent") -> tuple[Path, Path]:
-        release_dir = root / "release"
-        release_dir.mkdir()
-        artifact = release_dir / "OneAgent-0.2.0-dev-technical-preview-unsigned-macos-arm64.zip"
-        artifact.write_bytes(artifact_bytes)
-        manifest = {
-            "schema_version": 1,
-            "oneagent_version": "0.2.0-dev",
-            "channel": "technical-preview-unsigned",
-            "unsigned": True,
-            "platform": "macos",
-            "arch": "arm64",
-            "python": "3.12.13",
-            "built_at": "2026-07-26T10:14:28Z",
-            "agent_versions": {"codex": "0.145.0"},
-            "artifacts": [
-                {"file": artifact.name, "sha256": digest(artifact), "bytes": artifact.stat().st_size}
-            ],
-        }
-        manifest_path = release_dir / "release-manifest-macos-arm64.json"
-        manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
-        (release_dir / "SHA256SUMS-macos-arm64.txt").write_text(
-            f"{digest(artifact)}  {artifact.name}\n{digest(manifest_path)}  {manifest_path.name}\n",
-            encoding="utf-8",
-        )
-        channels = {
-            "schema_version": 1,
-            "product": {
-                "name": "OneAgent",
-                "tagline": "用一个可信的本地流程，激活你自己的 Agent、账号和 Provider。",
-            },
-            "channels": {
-                "technical-preview-unsigned": {
-                    "label": "未签名技术预览版",
-                    "published_at": "2026-07-28T00:00:00Z",
-                    "targets": [
-                        {
-                            "platform": "macos",
-                            "arch": "arm64",
-                            "status": "available",
-                            "verification": {
-                                "native_build": True,
-                                "cleanroom": "verified",
-                                "evidence": "security/#release-evidence",
-                            },
-                            "mirrors": [
-                                {
-                                    "id": "website",
-                                    "label": "官网下载",
-                                    "kind": "official",
-                                    "url": "downloads/{file}",
-                                    "primary": True,
-                                }
-                            ],
-                        },
-                        {
-                            "platform": "windows",
-                            "arch": "x64",
-                            "status": "verification-pending",
-                            "verification": {
-                                "native_build": False,
-                                "cleanroom": "not-recorded",
-                                "evidence": None,
-                            },
-                            "mirrors": [],
-                        },
-                    ],
-                },
-                "stable": {"label": "Stable", "published_at": None, "targets": []},
-            },
-        }
-        channels_path = root / "channels.json"
-        channels_path.write_text(json.dumps(channels, indent=2) + "\n", encoding="utf-8")
-        return release_dir, channels_path
-
-    def test_builds_a_public_index_from_verified_manifests(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            release_dir, channels_path = self.write_fixture(Path(tmp))
-            index = build_release_index(release_dir, channels_path)
-
-        preview = next(channel for channel in index["channels"] if channel["channel"] == "technical-preview-unsigned")
-        self.assertEqual(index["latest"]["technical-preview-unsigned"], "0.2.0-dev")
-        self.assertIsNone(index["latest"]["stable"])
-        self.assertTrue(preview["unsigned"])
-        macos = next(target for target in preview["targets"] if target["id"] == "macos-arm64")
-        self.assertEqual(macos["status"], "available")
-        self.assertEqual(macos["artifacts"][0]["downloads"][0]["url"], f"downloads/{macos['artifacts'][0]['file']}")
-        self.assertEqual(macos["artifacts"][0]["kind"], "binary")
-        windows = next(target for target in preview["targets"] if target["id"] == "windows-x64")
-        self.assertEqual(windows["artifacts"], [])
-
-    def test_rejects_an_available_target_without_cleanroom_evidence(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            release_dir, channels_path = self.write_fixture(Path(tmp))
-            channels = json.loads(channels_path.read_text(encoding="utf-8"))
-            channels["channels"]["technical-preview-unsigned"]["targets"][0]["verification"]["cleanroom"] = "not-recorded"
-            channels_path.write_text(json.dumps(channels), encoding="utf-8")
-            with self.assertRaisesRegex(ReleaseIndexError, "cleanroom"):
-                build_release_index(release_dir, channels_path)
-
-    def test_rejects_hash_drift_between_manifest_and_artifact(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            release_dir, channels_path = self.write_fixture(Path(tmp))
-            artifact = next(release_dir.glob("OneAgent-*.zip"))
-            artifact.write_bytes(b"tampered")
-            with self.assertRaisesRegex(ReleaseIndexError, "SHA-256"):
-                build_release_index(release_dir, channels_path)
-
-    def test_rejects_an_available_target_without_a_manifest(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            release_dir, channels_path = self.write_fixture(Path(tmp))
-            (release_dir / "release-manifest-macos-arm64.json").unlink()
-            with self.assertRaisesRegex(ReleaseIndexError, "manifest"):
-                build_release_index(release_dir, channels_path)
-
-    def test_rejects_an_external_mirror_without_the_verified_artifact_hash(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            release_dir, channels_path = self.write_fixture(Path(tmp))
-            channels = json.loads(channels_path.read_text(encoding="utf-8"))
-            channels["channels"]["technical-preview-unsigned"]["targets"][0]["mirrors"].append(
-                {
-                    "id": "domestic-mirror",
-                    "label": "国内镜像",
-                    "kind": "mirror",
-                    "url": "https://downloads.example.com/{file}",
-                    "verified_sha256": "0" * 64,
-                    "primary": False,
-                    "audit": {
-                        "uploaded_by": "release-manager",
-                        "uploaded_at": "2026-07-28T01:00:00Z",
-                        "verified_at": "2026-07-28T01:05:00Z",
-                        "withdrawal_owner": "security@example.com",
-                        "withdrawn": False,
-                        "withdrawn_at": None,
-                    },
-                }
-            )
-            channels_path.write_text(json.dumps(channels), encoding="utf-8")
-            with self.assertRaisesRegex(ReleaseIndexError, "External mirror SHA-256"):
-                build_release_index(release_dir, channels_path)
-
-    def test_rejects_an_available_target_without_one_primary_official_channel(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            release_dir, channels_path = self.write_fixture(Path(tmp))
-            channels = json.loads(channels_path.read_text(encoding="utf-8"))
-            channels["channels"]["technical-preview-unsigned"]["targets"][0]["mirrors"][0]["primary"] = False
-            channels_path.write_text(json.dumps(channels), encoding="utf-8")
-            with self.assertRaisesRegex(ReleaseIndexError, "primary official"):
-                build_release_index(release_dir, channels_path)
-
-    def test_rejects_an_available_channel_without_a_publish_timestamp(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            release_dir, channels_path = self.write_fixture(Path(tmp))
-            channels = json.loads(channels_path.read_text(encoding="utf-8"))
-            channels["channels"]["technical-preview-unsigned"]["published_at"] = None
-            channels_path.write_text(json.dumps(channels), encoding="utf-8")
-            with self.assertRaisesRegex(ReleaseIndexError, "published_at"):
-                build_release_index(release_dir, channels_path)
-
-    def test_rejects_a_download_url_that_escapes_the_site_base(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            release_dir, channels_path = self.write_fixture(Path(tmp))
-            channels = json.loads(channels_path.read_text(encoding="utf-8"))
-            channels["channels"]["technical-preview-unsigned"]["targets"][0]["mirrors"][0]["url"] = "../{file}"
-            channels_path.write_text(json.dumps(channels), encoding="utf-8")
-            with self.assertRaisesRegex(ReleaseIndexError, "download root"):
-                build_release_index(release_dir, channels_path)
-
-    def test_public_release_assets_only_include_available_targets(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-            release_dir, channels_path = self.write_fixture(root)
-            (release_dir / "unverified-windows.zip").write_bytes(b"not public")
-            index = build_release_index(release_dir, channels_path)
-            destination = root / "public-release"
-            copy_available_release_assets(index, release_dir, destination)
-
-            self.assertEqual(
-                {path.name for path in destination.iterdir()},
-                {
-                    "OneAgent-0.2.0-dev-technical-preview-unsigned-macos-arm64.zip",
-                    "release-manifest-macos-arm64.json",
-                    "SHA256SUMS-macos-arm64.txt",
-                    "release-index.json",
-                },
-            )
-
-
-class SiteCatalogTests(unittest.TestCase):
-    def test_projects_agent_support_without_turning_guides_into_managed_installs(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-            lock_path = root / "agents.lock.json"
-            lock_path.write_text(
-                json.dumps(
-                    {
-                        "schema_version": 1,
-                        "agents": {
-                            "managed": {
-                                "name": "Managed",
-                                "group": "auto",
-                                "config_mode": "auto",
-                                "config_adapter": "codex",
-                                "rank": 2,
-                                "platforms": ["macos"],
-                                "package": {"version": "1.0.0", "source": "https://example.com", "license": "MIT"},
-                            },
-                            "guided": {
-                                "name": "Guided",
-                                "group": "platform",
-                                "config_mode": "guide",
-                                "rank": 1,
-                                "platforms": ["macos", "windows"],
-                                "guide": "Use the official installer.",
-                            },
-                        },
-                    }
-                ),
-                encoding="utf-8",
-            )
-            provider_path = root / "providers.json"
-            provider_path.write_text(
-                json.dumps(
-                    {
-                        "schema_version": 1,
-                        "providers": {
-                            "example": {
-                                "name": "Example",
-                                "home": "https://example.com",
-                                "relationship": "referral",
-                                "disclosure": "商业合作",
-                                "referral_url": "https://example.com/ref",
-                                "protocols": {"openai": "implementation-supported"},
-                            }
-                        },
-                    }
-                ),
-                encoding="utf-8",
-            )
-            catalog = build_site_catalog(lock_path, provider_path)
-
-        self.assertEqual([agent["id"] for agent in catalog["agents"]], ["guided", "managed"])
-        guided = catalog["agents"][0]
-        self.assertFalse(guided["support"]["managedInstall"])
-        self.assertTrue(guided["support"]["officialInstallGuide"])
-        self.assertFalse(guided["support"]["managedConfig"])
-        self.assertIsNone(guided["protocol"])
-        managed = catalog["agents"][1]
-        self.assertEqual(managed["protocol"], "responses")
-        self.assertTrue(managed["support"]["managedInstall"])
-        self.assertTrue(managed["support"]["managedConfig"])
-        self.assertEqual(catalog["providers"][0]["relationship"], "referral")
-
-    def test_rejects_undisclosed_or_unsafe_provider_links(self):
-        lock_path = Path(__file__).resolve().parents[1] / "agents.lock.json"
-        with tempfile.TemporaryDirectory() as tmp:
-            provider_path = Path(tmp) / "providers.json"
-            provider_path.write_text(
-                json.dumps(
-                    {
-                        "schema_version": 1,
-                        "providers": {
-                            "unsafe": {
-                                "name": "Unsafe",
-                                "home": "javascript:alert(1)",
-                                "relationship": "none",
-                                "disclosure": "",
-                                "referral_url": "https://example.com/ref",
-                                "protocols": {"openai": "implementation-supported"},
-                            }
-                        },
-                    }
-                ),
-                encoding="utf-8",
-            )
-            with self.assertRaisesRegex(SiteCatalogError, "undisclosed commercial fields"):
-                build_site_catalog(lock_path, provider_path)
-            payload = json.loads(provider_path.read_text(encoding="utf-8"))
-            payload["providers"]["unsafe"]["referral_url"] = ""
-            provider_path.write_text(json.dumps(payload), encoding="utf-8")
-            with self.assertRaisesRegex(SiteCatalogError, "must use HTTPS"):
-                build_site_catalog(lock_path, provider_path)
-
-
-if __name__ == "__main__":
-    unittest.main()
diff --git a/tests/test_edge_cases.py b/tests/test_edge_cases.py
deleted file mode 100644
index 88e2576f..00000000
--- a/tests/test_edge_cases.py
+++ /dev/null
@@ -1,1458 +0,0 @@
-from __future__ import annotations
-
-import io
-import json
-import socket
-import subprocess
-import tempfile
-import tomllib
-import unittest
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-from urllib.error import HTTPError, URLError
-
-from oneagent import catalog, installer as installer_module
-from oneagent.errors import OneAgentError
-from oneagent.installer import (
-    InstallOptions,
-    Runtime,
-    _load_json,
-    _merge_codex_toml,
-    _next_step,
-    _python_312_for_uv,
-    _run_acl,
-    _write_agent_config,
-    _version_from_output,
-    active_profile_id,
-    atomic_write,
-    backup_file,
-    install_locked_agent,
-    install_many,
-    installed_version,
-    list_profiles,
-    load_profile,
-    save_profile,
-    profile_store_path,
-    secrets_path,
-    status_payload,
-    validate_profile_id,
-    write_aider_config,
-    write_claude_config,
-    write_codex_config,
-    write_openai_compatible_config,
-    write_profile,
-)
-from oneagent.providers import (
-    _protocol_request,
-    _unsupported_protocol,
-    PROTOCOL_ANTHROPIC,
-    PROTOCOL_OPENAI,
-    agent_protocol,
-    anthropic_messages_url,
-    chat_probe,
-    list_models,
-    openai_base_url,
-    pick_chat_model,
-    protocol_probe,
-    provider_base,
-    provider_config_base,
-    provider_home,
-    resolve_probe_model,
-    validate_base_url,
-)
-
-
-class FakeResponse:
-    def __init__(self, data: bytes = b"{}", status: int = 200):
-        self.data = data
-        self.status = status
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, *_args):
-        return False
-
-    def read(self):
-        return self.data
-
-
-class ProfileStoreTests(unittest.TestCase):
-    def _runtime(self, tmp: str) -> Runtime:
-        return Runtime.create(home=Path(tmp), os_id="linux", which=lambda _name: None)
-
-    def test_validate_profile_id_rules(self):
-        self.assertEqual(validate_profile_id("ppio-deepseek_v3"), "ppio-deepseek_v3")
-        for bad in ("", "Upper", "-lead", "a" * 65, "sp ace", "../escape", None, 42):
-            with self.subTest(bad=bad):
-                with self.assertRaises(OneAgentError):
-                    validate_profile_id(bad)
-
-    def test_profile_state_starts_empty(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            self.assertEqual(load_profile(runtime), (None, None))
-            self.assertEqual(list_profiles(runtime), [])
-            self.assertIsNone(active_profile_id(runtime))
-
-    def test_legacy_v1_profile_migrates_to_the_default_profile(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            legacy = {
-                "schema_version": 1,
-                "provider": "ppio",
-                "base_url": "https://api.ppio.com/openai",
-                "model": "deepseek-v3",
-                "config_mode": "provider",
-                "agent_ids": ["codex"],
-                "activated_at": "2026-07-22T00:00:00Z",
-            }
-            oneagent_dir = runtime.home / ".oneagent"
-            oneagent_dir.mkdir(parents=True)
-            (oneagent_dir / "profile.json").write_text(json.dumps(legacy), encoding="utf-8")
-
-            profile, error = load_profile(runtime)
-            self.assertIsNone(error)
-            self.assertEqual(profile["id"], "default")
-            self.assertEqual(profile["provider"], "ppio")
-            self.assertEqual(profile["created_at"], "2026-07-22T00:00:00Z")
-            # The pointer replaced the legacy file, which survives as a backup.
-            pointer = json.loads((oneagent_dir / "profile.json").read_text(encoding="utf-8"))
-            self.assertEqual(pointer, {"schema_version": 2, "active": "default"})
-            self.assertTrue(list(oneagent_dir.glob("profile.json.backup-*")))
-            # Reading again takes the v2 path, not the migration.
-            again, _ = load_profile(runtime)
-            self.assertEqual(again["model"], "deepseek-v3")
-            self.assertEqual(active_profile_id(runtime), "default")
-
-    def test_migration_failure_is_reported_and_the_original_survives(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            legacy = {
-                "schema_version": 1,
-                "provider": "ppio",
-                "base_url": None,
-                "model": "m",
-                "config_mode": "provider",
-                "agent_ids": [],
-                "activated_at": "x",
-            }
-            oneagent_dir = runtime.home / ".oneagent"
-            oneagent_dir.mkdir(parents=True)
-            original = oneagent_dir / "profile.json"
-            original.write_text(json.dumps(legacy), encoding="utf-8")
-            with patch(
-                "oneagent.installer._write_profile_store",
-                side_effect=OneAgentError("CONFIG_WRITE_FAILED", "read-only"),
-            ):
-                profile, error = load_profile(runtime)
-            self.assertIsNone(profile)
-            self.assertIn("Cannot migrate", error)
-            # The pointer was never written: the v1 file stays untouched.
-            self.assertEqual(json.loads(original.read_text(encoding="utf-8"))["schema_version"], 1)
-
-    def test_profile_schema_failures_are_reported_not_raised(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            path = runtime.home / ".oneagent" / "profile.json"
-            path.parent.mkdir(parents=True)
-            for content, expected in (
-                ("{", "invalid-json"),
-                ("[]", "Unsupported environment profile schema"),
-                ('{"schema_version":9}', "Unsupported environment profile schema"),
-            ):
-                with self.subTest(content=content):
-                    path.write_text(content, encoding="utf-8")
-                    _, error = load_profile(runtime)
-                    if expected == "invalid-json":
-                        self.assertTrue(error)
-                    else:
-                        self.assertEqual(error, expected)
-            # v1 without a timestamp still migrates.
-            path.write_text('{"schema_version":1,"provider":"x"}', encoding="utf-8")
-            profile, error = load_profile(runtime)
-            self.assertIsNone(error)
-            self.assertEqual(profile["id"], "default")
-            # A v2 pointer to a missing store entry names the profile.
-            path.write_text('{"schema_version":2,"active":"ghost"}', encoding="utf-8")
-            _, error = load_profile(runtime)
-            self.assertIn("ghost", error)
-            self.assertEqual(active_profile_id(runtime), "ghost")
-            # Corrupt and non-dict store files are reported, not raised.
-            store = runtime.home / ".oneagent" / "profiles"
-            store.mkdir(parents=True, exist_ok=True)
-            (store / "ghost.json").write_text("{", encoding="utf-8")
-            _, error = load_profile(runtime)
-            self.assertTrue(error)
-            (store / "ghost.json").write_text("[]", encoding="utf-8")
-            _, error = load_profile(runtime)
-            self.assertIn("corrupt", error)
-
-    def test_active_profile_id_survives_unreadable_pointers(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            path = runtime.home / ".oneagent" / "profile.json"
-            path.parent.mkdir(parents=True)
-            path.write_text("{", encoding="utf-8")
-            self.assertIsNone(active_profile_id(runtime))
-            path.write_text("[]", encoding="utf-8")
-            self.assertIsNone(active_profile_id(runtime))
-            path.write_text('{"schema_version":1}', encoding="utf-8")
-            self.assertIsNone(active_profile_id(runtime))
-
-    def test_a_tampered_pointer_cannot_escape_the_profile_store(self):
-        # profile.json is a file on disk, so its "active" value is untrusted
-        # even though OneAgent writes it. Without validation the pointer names
-        # any path: load_profile would read an arbitrary .json as a profile and
-        # secrets_path would place a plaintext key outside secrets/.
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            store = runtime.home / ".oneagent" / "profiles"
-            store.mkdir(parents=True)
-            outside = runtime.home / "elsewhere"
-            outside.mkdir()
-            (outside / "stolen.json").write_text(
-                json.dumps({"schema_version": 2, "id": "stolen", "model": "LEAKED"}),
-                encoding="utf-8",
-            )
-            pointer = runtime.home / ".oneagent" / "profile.json"
-            pointer.write_text(
-                json.dumps({"schema_version": 2, "active": "../../elsewhere/stolen"}),
-                encoding="utf-8",
-            )
-
-            profile, error = load_profile(runtime)
-            self.assertIsNone(profile)
-            self.assertIn("Profile ID must", error)
-            self.assertIsNone(active_profile_id(runtime))
-
-            for bad in ("../../evil", "a/b", "..", "/abs"):
-                with self.subTest(bad=bad):
-                    with self.assertRaises(OneAgentError):
-                        secrets_path(runtime, bad)
-                    with self.assertRaises(OneAgentError):
-                        profile_store_path(runtime, bad)
-
-    def test_list_profiles_skips_unreadable_and_id_less_files(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            store = runtime.home / ".oneagent" / "profiles"
-            store.mkdir(parents=True)
-            (store / "junk.json").write_text("not-json", encoding="utf-8")
-            (store / "noid.json").write_text('{"provider":"ppio"}', encoding="utf-8")
-            save_profile(runtime, profile_id="real", provider="ppio", model="m", agent_ids=["codex"])
-            listing = list_profiles(runtime)
-            self.assertEqual([item["id"] for item in listing], ["real"])
-
-    def test_save_profile_isolates_key_material_and_keeps_history(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            stored = save_profile(
-                runtime,
-                profile_id="ppio-deepseek",
-                label="PPIO DeepSeek",
-                provider="ppio",
-                model="deepseek-v3",
-                agent_ids=["opencode", "codex"],
-                api_key="sk-secret",
-            )
-            self.assertEqual(stored["agent_ids"], ["codex", "opencode"])
-            entry = list_profiles(runtime)[0]
-            self.assertTrue(entry["has_key"])
-            # The profile file itself must not carry the key.
-            profile_text = (runtime.home / ".oneagent" / "profiles" / "ppio-deepseek.json").read_text(encoding="utf-8")
-            self.assertNotIn("sk-secret", profile_text)
-            secret = secrets_path(runtime, "ppio-deepseek").read_text(encoding="utf-8")
-            self.assertIn("sk-secret", secret)
-            # Saving again keeps the label and creation time, replaces the model,
-            # and leaves the stored key in place when none is supplied.
-            first_created = entry["created_at"]
-            save_profile(runtime, profile_id="ppio-deepseek", provider="ppio", model="model-b", agent_ids=["codex"])
-            again = list_profiles(runtime)[0]
-            self.assertEqual(again["label"], "PPIO DeepSeek")
-            self.assertEqual(again["created_at"], first_created)
-            self.assertEqual(again["model"], "model-b")
-            self.assertTrue(again["has_key"])
-
-    def test_save_profile_validates_provider_and_id(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            with self.assertRaises(OneAgentError):
-                save_profile(runtime, profile_id="ok-id", provider="nope", model="m", agent_ids=["codex"])
-            with self.assertRaises(OneAgentError):
-                save_profile(runtime, profile_id="../bad", provider="ppio", model="m", agent_ids=["codex"])
-            with self.assertRaises(OneAgentError):
-                save_profile(runtime, profile_id="custom-naked", provider="custom", model="m", agent_ids=["codex"])
-            # A custom provider with a valid base is fine.
-            stored = save_profile(
-                runtime,
-                profile_id="custom-local",
-                provider="custom",
-                api_base_url="http://127.0.0.1:9000",
-                model="m",
-                agent_ids=["codex"],
-            )
-            self.assertEqual(stored["base_url"], "http://127.0.0.1:9000")
-
-    def test_write_profile_upserts_the_active_profile_and_merges_agents(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            path = write_profile(
-                runtime,
-                agents=["codex"],
-                configure=True,
-                provider="ppio",
-                base_url="https://api.ppio.com/openai",
-                model="deepseek-v3",
-                api_key="sk-a",
-            )
-            self.assertEqual(json.loads(path.read_text(encoding="utf-8")), {"schema_version": 2, "active": "default"})
-            # Same provider+model merges agents instead of replacing them.
-            write_profile(
-                runtime,
-                agents=["opencode"],
-                configure=True,
-                provider="ppio",
-                base_url="https://api.ppio.com/openai",
-                model="deepseek-v3",
-            )
-            profile, error = load_profile(runtime)
-            self.assertIsNone(error)
-            self.assertEqual(profile["agent_ids"], ["codex", "opencode"])
-            self.assertEqual(profile["schema_version"], 2)
-            # A different provider replaces the environment without merging.
-            write_profile(runtime, agents=["aider"], configure=True, provider="novita", base_url="", model="model-x")
-            profile, _ = load_profile(runtime)
-            self.assertEqual(profile["provider"], "novita")
-            self.assertEqual(profile["agent_ids"], ["aider"])
-            # The existing-account path writes neither a model nor secrets.
-            write_profile(runtime, agents=["codex"], configure=False, provider="ppio", base_url="", model="")
-            profile, _ = load_profile(runtime)
-            self.assertEqual(profile["config_mode"], "existing-account")
-            self.assertIsNone(profile["model"])
-            # Key material lives only in the secret store, never the profile.
-            stored_text = (runtime.home / ".oneagent" / "profiles" / "default.json").read_text(encoding="utf-8")
-            self.assertNotIn("sk-a", stored_text)
-            self.assertIn("sk-a", secrets_path(runtime, "default").read_text(encoding="utf-8"))
-
-    def test_status_payload_exposes_profiles_without_key_material(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = self._runtime(tmp)
-            write_profile(
-                runtime,
-                agents=["codex"],
-                configure=True,
-                provider="ppio",
-                base_url="https://api.ppio.com/openai",
-                model="deepseek-v3",
-                api_key="sk-a",
-            )
-            payload = status_payload(runtime)
-            self.assertEqual(payload["activeProfile"], "default")
-            summary = payload["profiles"]
-            self.assertEqual(len(summary), 1)
-            self.assertEqual(summary[0]["id"], "default")
-            self.assertEqual(summary[0]["agentIds"], ["codex"])
-            self.assertTrue(summary[0]["hasKey"])
-            self.assertNotIn("sk-a", json.dumps(payload))
-
-
-class CatalogEdgeTests(unittest.TestCase):
-    def test_resource_root_and_manifest_failures(self):
-        with patch.object(catalog.sys, "_MEIPASS", "/tmp/oneagent-bundle", create=True):
-            self.assertEqual(catalog.resource_root(), Path("/tmp/oneagent-bundle"))
-        with tempfile.TemporaryDirectory() as tmp:
-            missing = Path(tmp) / "missing.json"
-            with self.assertRaises(OneAgentError):
-                catalog.load_manifest(missing)
-            invalid = Path(tmp) / "invalid.json"
-            invalid.write_text("{", encoding="utf-8")
-            with self.assertRaises(OneAgentError):
-                catalog.load_manifest(invalid)
-            invalid.write_text('{"schema_version":2,"agents":[]}', encoding="utf-8")
-            with self.assertRaises(OneAgentError):
-                catalog.load_manifest(invalid)
-
-    def test_platform_and_home_variants(self):
-        with patch("oneagent.catalog.platform.system", return_value="Darwin"), patch("oneagent.catalog.platform.machine", return_value="arm64"):
-            self.assertEqual(catalog.current_platform(), {"os": "macos", "arch": "arm64", "shell": "bash"})
-        with patch("oneagent.catalog.platform.system", return_value="Windows"), patch("oneagent.catalog.platform.machine", return_value="AMD64"):
-            self.assertEqual(catalog.current_platform(), {"os": "windows", "arch": "x64", "shell": "powershell"})
-        with patch("oneagent.catalog.platform.system", return_value="Linux"), patch("oneagent.catalog.platform.machine", return_value="x86_64"):
-            self.assertEqual(catalog.current_platform()["os"], "linux")
-
-        self.assertEqual(catalog.resolve_home({"ONEAGENT_HOME": "~/oneagent-test"}, "linux"), Path("~/oneagent-test").expanduser())
-        self.assertEqual(catalog.resolve_home({"HOMEDRIVE": "C:", "HOMEPATH": "\\Users\\Name"}, "windows"), Path("C:\\Users\\Name"))
-        self.assertEqual(catalog.resolve_home({"HOMEDRIVE": "C:", "HOME": "/fallback-home"}, "windows"), Path("/fallback-home"))
-        self.assertEqual(catalog.resolve_home({"HOME": "/tmp/home"}, "linux"), Path("/tmp/home"))
-        with patch("oneagent.catalog.Path.home", return_value=Path("/fallback")):
-            self.assertEqual(catalog.resolve_home({}, "linux"), Path("/fallback"))
-
-    def test_public_catalog_exposes_windows_note_only_on_windows(self):
-        with patch("oneagent.catalog.current_platform", return_value={"os": "windows", "arch": "x64", "shell": "powershell"}):
-            by_id = {item["id"]: item for item in catalog.public_catalog()}
-        self.assertTrue(by_id["opencode"]["platformNote"])
-
-    def test_public_providers_omits_anthropic_base_when_absent(self):
-        # Both built-in providers publish one, so this branch is only reachable
-        # with a provider that does not — and it must omit the key rather than
-        # emit null, which the frontend declares as optional.
-        with patch.dict(
-            catalog.PROVIDERS,
-            {"openai-only": {"name": "X", "home": "https://x.invalid/", "base_url": "https://x.invalid/v1"}},
-            clear=False,
-        ):
-            public = catalog.public_providers()
-        self.assertNotIn("anthropic_base_url", public["openai-only"])
-        self.assertIn("anthropic_base_url", public["ppio"])
-
-    def test_catalog_ranks_widely_used_agents_ahead_of_niche_ones(self):
-        # The overview leads with this order, so it is a product decision rather
-        # than an accident of dict insertion order in agents.lock.json.
-        order = [item["id"] for item in catalog.public_catalog()]
-        self.assertEqual(order[:4], ["codex", "claude-code", "cursor", "opencode"])
-        for niche in ("kilo-cli", "aider"):
-            with self.subTest(agent=niche):
-                self.assertLess(order.index("cursor"), order.index(niche))
-                self.assertLess(order.index("openclaw"), order.index(niche))
-        # Every Agent carries an explicit rank; a missing one would silently
-        # collapse to the tail.
-        self.assertTrue(all(item["rank"] < 99 for item in catalog.public_catalog()))
-
-
-class ProtocolEdgeTests(unittest.TestCase):
-    def test_agent_protocol_mapping_covers_every_auto_adapter(self):
-        adapters = {
-            meta["config_adapter"]: agent_id
-            for agent_id, meta in catalog.agent_catalog().items()
-            if meta["config_mode"] == "auto"
-        }
-        self.assertEqual(
-            {adapter: agent_protocol(adapter) for adapter in adapters},
-            {
-                "codex": "responses",
-                "claude-code": "anthropic",
-                "opencode": "openai",
-                "kilo-cli": "openai",
-                "aider": "openai",
-            },
-        )
-        # An adapter added without a protocol entry must not silently probe a
-        # protocol it does not speak; OpenAI-compatible is the documented default.
-        self.assertEqual(agent_protocol("brand-new-adapter"), "openai")
-
-    def test_anthropic_messages_url_normalises_both_base_shapes(self):
-        cases = {
-            "https://api.ppio.com/anthropic": "https://api.ppio.com/anthropic/v1/messages",
-            "https://api.novita.ai/anthropic/": "https://api.novita.ai/anthropic/v1/messages",
-            "https://proxy.test/v1": "https://proxy.test/v1/messages",
-            "https://proxy.test/v1/messages": "https://proxy.test/v1/messages",
-            "https://proxy.test/messages": "https://proxy.test/v1/messages",
-        }
-        for base, expected in cases.items():
-            with self.subTest(base=base):
-                self.assertEqual(anthropic_messages_url(base), expected)
-
-    def test_unsupported_protocol_classification(self):
-        # Permanent: the endpoint says the pair cannot work.
-        self.assertTrue(_unsupported_protocol(404, ""))
-        self.assertTrue(_unsupported_protocol(405, ""))
-        self.assertTrue(_unsupported_protocol(501, ""))
-        self.assertTrue(_unsupported_protocol(400, '{"message":"model: x does not support endpoint: responses"}'))
-        self.assertTrue(_unsupported_protocol(500, '{"error":{"message":"not implemented"}}'))
-        self.assertTrue(_unsupported_protocol(422, "Unsupported endpoint"))
-        # Transient: a bare 500 or an overloaded upstream must stay retryable.
-        self.assertFalse(_unsupported_protocol(500, '{"error":{"message":"internal server error"}}'))
-        self.assertFalse(_unsupported_protocol(503, "the upstream load is saturated"))
-        self.assertFalse(_unsupported_protocol(429, "quota exceeded"))
-        self.assertFalse(_unsupported_protocol(400, '{"message":"invalid api key"}'))
-
-    def test_each_protocol_builds_its_own_endpoint_and_payload(self):
-        built = {
-            protocol: _protocol_request(
-                protocol, provider="custom", custom_base="https://proxy.test/v1", api_key="k", model="m"
-            )
-            for protocol in ("openai", "responses", "anthropic")
-        }
-        self.assertEqual(built["openai"].full_url, "https://proxy.test/v1/chat/completions")
-        self.assertEqual(built["responses"].full_url, "https://proxy.test/v1/responses")
-        self.assertEqual(built["anthropic"].full_url, "https://proxy.test/v1/messages")
-
-        # Responses takes `input`, not `messages`; Anthropic needs its own headers.
-        self.assertIn("input", json.loads(built["responses"].data))
-        self.assertIn("messages", json.loads(built["openai"].data))
-        self.assertEqual(built["anthropic"].get_header("X-api-key"), "k")
-        self.assertEqual(built["anthropic"].get_header("Anthropic-version"), "2023-06-01")
-        self.assertIsNone(built["openai"].get_header("X-api-key"))
-
-    def test_protocol_probe_rejects_unknown_protocol_and_missing_key(self):
-        with self.assertRaises(OneAgentError):
-            protocol_probe(protocol="openai", provider="custom", api_key="", model="m", custom_base="https://x.test/v1")
-        with self.assertRaises(OneAgentError):
-            protocol_probe(protocol="grpc", provider="custom", api_key="k", model="m", custom_base="https://x.test/v1")
-
-    def test_protocol_probe_reports_unsupported_pairs_as_permanent(self):
-        error = HTTPError(
-            "https://proxy.test/v1/responses", 400, "Bad Request", {},
-            io.BytesIO(b'{"code":400,"reason":"INVALID_REQUEST_BODY","message":"model: glm does not support endpoint: responses"}'),
-        )
-        with patch("oneagent.providers.urlopen", side_effect=error):
-            result = protocol_probe(
-                protocol="responses", provider="custom", api_key="k", model="glm", custom_base="https://proxy.test/v1"
-            )
-        self.assertFalse(result["ok"])
-        self.assertEqual(result["error_code"], "PROTOCOL_UNSUPPORTED")
-        self.assertFalse(result["retryable"])
-        self.assertEqual(result["protocol"], "responses")
-        self.assertIn("OpenAI Responses", result["message"])
-
-    def test_protocol_probe_keeps_transient_failures_retryable(self):
-        error = HTTPError(
-            "https://proxy.test/v1/responses", 503, "Service Unavailable", {},
-            io.BytesIO(b'{"error":{"message":"the upstream load is saturated"}}'),
-        )
-        with patch("oneagent.providers.urlopen", side_effect=error):
-            result = protocol_probe(
-                protocol="responses", provider="custom", api_key="k", model="m", custom_base="https://proxy.test/v1"
-            )
-        self.assertFalse(result["ok"])
-        self.assertNotEqual(result["error_code"], "PROTOCOL_UNSUPPORTED")
-        self.assertTrue(result["retryable"])
-        self.assertEqual(result["protocol"], "responses")
-
-    def test_protocol_probe_success_reports_the_protocol_label(self):
-        with patch("oneagent.providers.urlopen", return_value=FakeResponse(b"{}", 200)):
-            result = protocol_probe(
-                protocol="anthropic", provider="custom", api_key="k", model="m", custom_base="https://proxy.test/v1"
-            )
-        self.assertTrue(result["ok"])
-        self.assertEqual(result["protocol"], "anthropic")
-        self.assertIn("Anthropic Messages", result["message"])
-
-    def test_unreadable_error_body_falls_back_to_generic_handling(self):
-        class Unreadable(io.BytesIO):
-            def read(self, *_args):
-                raise OSError("stream closed")
-
-        error = HTTPError("https://proxy.test/v1/responses", 400, "Bad Request", {}, Unreadable(b""))
-        with patch("oneagent.providers.urlopen", side_effect=error):
-            result = protocol_probe(
-                protocol="responses", provider="custom", api_key="k", model="m", custom_base="https://proxy.test/v1"
-            )
-        self.assertFalse(result["ok"])
-        self.assertNotEqual(result["error_code"], "PROTOCOL_UNSUPPORTED")
-
-
-class ProviderEdgeTests(unittest.TestCase):
-    def test_url_and_provider_validation_edges(self):
-        for value in ("", "ftp://example.com", "https:///missing-host"):
-            with self.subTest(value=value), self.assertRaises(OneAgentError):
-                validate_base_url(value)
-        self.assertEqual(provider_base("ppio"), "https://api.ppio.com/openai")
-        self.assertEqual(provider_base("custom", "http://127.0.0.1:9000/"), "http://127.0.0.1:9000")
-        with self.assertRaises(OneAgentError):
-            provider_base("custom")
-        self.assertEqual(provider_config_base("ppio", "", PROTOCOL_ANTHROPIC), "https://api.ppio.com/anthropic")
-        self.assertEqual(provider_config_base("novita", "", PROTOCOL_ANTHROPIC), "https://api.novita.ai/anthropic")
-        # A non-Anthropic protocol keeps the OpenAI-compatible base.
-        self.assertEqual(provider_config_base("ppio", "", PROTOCOL_OPENAI), "https://api.ppio.com/openai")
-        self.assertEqual(provider_config_base("ppio", "https://override.example.com", PROTOCOL_ANTHROPIC), "https://override.example.com")
-        self.assertEqual(provider_config_base("custom", "http://127.0.0.1:9000", PROTOCOL_ANTHROPIC), "http://127.0.0.1:9000")
-        with self.assertRaises(OneAgentError):
-            provider_base("unknown")
-        with self.assertRaises(OneAgentError):
-            provider_home("custom")
-        self.assertEqual(openai_base_url("https://example.com/v1/responses"), "https://example.com/v1")
-        self.assertEqual(openai_base_url("https://example.com/v1/models"), "https://example.com/v1")
-
-    def test_fallback_probe_model_is_provider_specific_and_never_a_foreign_id(self):
-        # The probe gates the wizard, so the fallback model must be one the
-        # provider actually serves. It used to be a hardcoded "gpt-4.1", which
-        # exists on neither built-in provider: every connection test failed with
-        # an auth error and no correct key could get past the provider step.
-        # The IDs also differ per provider, so one shared constant cannot work.
-        # The fallback is now only the narrow path behind resolve_probe_model.
-        self.assertNotEqual(catalog.fallback_probe_model("ppio"), catalog.fallback_probe_model("novita"))
-        for provider in ("ppio", "novita"):
-            with self.subTest(provider=provider):
-                model = catalog.fallback_probe_model(provider)
-                self.assertTrue(model)
-                self.assertNotIn("gpt-", model)
-                self.assertEqual(model, catalog.PROVIDERS[provider]["fallback_probe_model"])
-        # An unknown provider still yields a usable ID rather than an empty
-        # model, which would send a request no endpoint can answer.
-        self.assertTrue(catalog.fallback_probe_model("custom"))
-
-    def test_install_resolves_an_empty_model_before_writing_configs(self):
-        # InstallOptions defaults to no model; writing "" into an Agent config
-        # would leave a file that looks configured but cannot serve a request.
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            runtime = Runtime(
-                home=home,
-                os_id="macos",
-                runner=lambda *a, **k: subprocess.CompletedProcess(a[0] if a else [], 0, "1.0.0", ""),
-                which=lambda name: f"/usr/bin/{name}",
-                env={},
-            )
-            result = install_many(
-                InstallOptions(agents=["codex"], provider="ppio", api_key="sk-test", skip_test=True, home=home),
-                runtime,
-            )
-            self.assertTrue(result["ok"], result)
-            written = tomllib.loads((home / ".codex" / "config.toml").read_text(encoding="utf-8"))
-        self.assertEqual(written["model"], catalog.fallback_probe_model("ppio"))
-
-    def test_probe_success_default_model_and_network_error(self):
-        with patch("oneagent.providers.urlopen", return_value=FakeResponse(status=204)) as request:
-            result = chat_probe(provider="ppio", api_key="key", model="")
-        self.assertTrue(result["ok"])
-        sent = json.loads(request.call_args.args[0].data.decode())
-        self.assertEqual(sent["model"], catalog.fallback_probe_model("ppio"))
-        with patch("oneagent.providers.urlopen", side_effect=URLError("connection refused")):
-            result = chat_probe(provider="ppio", api_key="key", model="m")
-        self.assertEqual(result["error_code"], "PROVIDER_UNREACHABLE")
-        with patch("oneagent.providers.urlopen", side_effect=URLError(socket.timeout("timed out"))):
-            self.assertEqual(chat_probe(provider="ppio", api_key="key", model="m")["error_code"], "TIMEOUT")
-        with self.assertRaises(OneAgentError):
-            chat_probe(provider="ppio", api_key="", model="m")
-
-    def test_pick_chat_model_prefers_chat_capable_ids(self):
-        mixed = [
-            "whisper-large-v3",
-            "bge-reranker-v2",
-            "text-embeddings-large",
-            "qwen-vl-max",
-            "deepseek-v3",
-            "gpt-5.6-terra",
-        ]
-        self.assertEqual(pick_chat_model(mixed), "deepseek-v3")
-        # Markers match on separators only, so IDs that merely contain a
-        # marker substring stay eligible.
-        self.assertEqual(pick_chat_model(["resolver-1", "evolve-chat"]), "resolver-1")
-        # When every listed model looks non-chat, the first entry is the least
-        # surprising choice; the probe failure will explain itself.
-        self.assertEqual(pick_chat_model(["text-embedding-3-small", "whisper-1"]), "text-embedding-3-small")
-
-    def test_resolve_probe_model_prefers_live_ids_without_extra_round_trips(self):
-        # A user-chosen model short-circuits discovery: once the user has
-        # decided, probing must not cost an extra request.
-        with patch("oneagent.providers.list_models", side_effect=AssertionError("must not run")):
-            self.assertEqual(resolve_probe_model(provider="ppio", api_key="k", model="chosen"), "chosen")
-        # Without a key, discovery is skipped outright (list_models refuses it).
-        with patch("oneagent.providers.list_models", side_effect=AssertionError("must not run")):
-            self.assertEqual(resolve_probe_model(provider="ppio", api_key=""), catalog.fallback_probe_model("ppio"))
-        # Discovery success: the first chat-capable model, not the list head.
-        listing = {"ok": True, "models": ["text-embedding-3-small", "deepseek-v3"]}
-        with patch("oneagent.providers.list_models", return_value=listing) as discovery:
-            self.assertEqual(resolve_probe_model(provider="ppio", api_key="k"), "deepseek-v3")
-        discovery.assert_called_once()
-        # Discovery failing or empty falls back to the catalog ID, never raises.
-        for stale in ({"ok": False, "models": []}, {"ok": True, "models": []}):
-            with self.subTest(stale=stale), patch("oneagent.providers.list_models", return_value=stale):
-                self.assertEqual(
-                    resolve_probe_model(provider="novita", api_key="k"), catalog.fallback_probe_model("novita")
-                )
-
-    def test_install_resolves_an_empty_model_from_live_discovery(self):
-        ok_probe = {"ok": True, "message": "ok", "error_code": None, "retryable": False, "protocol": "responses"}
-        listing = {"ok": True, "models": ["text-embedding-3-small", "moonshot-v1"]}
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            runtime = Runtime(
-                home=home,
-                os_id="macos",
-                runner=lambda *a, **k: subprocess.CompletedProcess(a[0] if a else [], 0, "1.0.0", ""),
-                which=lambda name: f"/usr/bin/{name}",
-                env={},
-            )
-            with (
-                patch("oneagent.installer.protocol_probe", return_value=ok_probe),
-                patch("oneagent.providers.list_models", return_value=listing) as discovery,
-            ):
-                result = install_many(
-                    InstallOptions(agents=["codex"], provider="ppio", api_key="sk-test", home=home), runtime
-                )
-            self.assertTrue(result["ok"], result)
-            written = tomllib.loads((home / ".codex" / "config.toml").read_text(encoding="utf-8"))
-        discovery.assert_called_once()
-        self.assertEqual(written["model"], "moonshot-v1")
-
-    def test_install_falls_back_when_discovery_fails_and_never_under_skip_test(self):
-        # Discovery failure keeps the install possible: the catalog fallback
-        # goes into the config, and the probe (patched) decides the outcome.
-        # Under skip_test no discovery attempt may happen at all.
-        ok_probe = {"ok": True, "message": "ok", "error_code": None, "retryable": False, "protocol": "responses"}
-        for skip_test in (False, True):
-            with self.subTest(skip_test=skip_test):
-                with tempfile.TemporaryDirectory() as tmp:
-                    home = Path(tmp)
-                    runtime = Runtime(
-                        home=home,
-                        os_id="macos",
-                        runner=lambda *a, **k: subprocess.CompletedProcess(a[0] if a else [], 0, "1.0.0", ""),
-                        which=lambda name: f"/usr/bin/{name}",
-                        env={},
-                    )
-                    with (
-                        patch("oneagent.installer.protocol_probe", return_value=ok_probe),
-                        patch(
-                            "oneagent.providers.list_models",
-                            side_effect=AssertionError("discovery must not run") if skip_test else None,
-                            return_value={"ok": False, "models": []},
-                        ),
-                    ):
-                        result = install_many(
-                            InstallOptions(
-                                agents=["codex"], provider="ppio", api_key="sk-test", home=home, skip_test=skip_test
-                            ),
-                            runtime,
-                        )
-                    self.assertTrue(result["ok"], result)
-                    written = tomllib.loads((home / ".codex" / "config.toml").read_text(encoding="utf-8"))
-                self.assertEqual(written["model"], catalog.fallback_probe_model("ppio"))
-
-    def test_model_response_shapes_and_errors(self):
-        with patch("oneagent.providers.urlopen", return_value=FakeResponse(b'["a",{"id":"b"},{"ignored":true}]')):
-            self.assertEqual(list_models(provider="ppio", api_key="key")["models"], ["a", "b"])
-        with patch("oneagent.providers.urlopen", return_value=FakeResponse(b'{"data":{"id":"bad"}}')):
-            result = list_models(provider="ppio", api_key="key")
-        self.assertEqual(result["error_code"], "MODELS_UNSUPPORTED")
-        with patch("oneagent.providers.urlopen", return_value=FakeResponse(b"not-json")):
-            result = list_models(provider="ppio", api_key="key")
-        self.assertEqual(result["error_code"], "MODELS_UNSUPPORTED")
-        with self.assertRaises(OneAgentError):
-            list_models(provider="ppio", api_key="")
-
-        error = HTTPError("https://example.com", 401, "Unauthorized", {}, io.BytesIO())
-        with patch("oneagent.providers.urlopen", side_effect=error):
-            result = list_models(provider="ppio", api_key="key")
-        self.assertIn("Enter model ID manually", result["message"])
-
-
-class InstallerEdgeTests(unittest.TestCase):
-    def test_backup_collision_and_profile_corruption(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            path = Path(tmp) / "config.json"
-            path.write_text("one", encoding="utf-8")
-            (Path(tmp) / "config.json.backup-fixed").write_text("old", encoding="utf-8")
-            with patch("oneagent.installer._timestamp", return_value="fixed"):
-                backup = backup_file(path)
-            self.assertEqual(backup.name, "config.json.backup-fixed-1")
-
-            runtime = Runtime.create(home=Path(tmp), os_id="linux")
-            profile = Path(tmp) / ".oneagent" / "profile.json"
-            profile.parent.mkdir()
-            profile.write_text("{", encoding="utf-8")
-            self.assertIsNotNone(load_profile(runtime)[1])
-            profile.write_text('{"schema_version":2}', encoding="utf-8")
-            self.assertEqual(load_profile(runtime)[1], "Unsupported environment profile schema")
-
-    def test_acl_and_atomic_write_fail_before_publish(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="windows", which=lambda _name: None)
-            with self.assertRaises(OneAgentError):
-                _run_acl(runtime, Path(tmp), directory=True)
-
-            calls = 0
-
-            def runner(args, **_kwargs):
-                nonlocal calls
-                calls += 1
-                return subprocess.CompletedProcess(args, 1 if calls >= 6 else 0, "", "")
-
-            runtime = Runtime.create(
-                home=Path(tmp),
-                os_id="windows",
-                runner=runner,
-                which=lambda name: "icacls.exe" if name == "icacls" else None,
-                env={"USERNAME": "tester"},
-            )
-            target = Path(tmp) / "secret.txt"
-            target.write_text("original", encoding="utf-8")
-            with self.assertRaises(OneAgentError):
-                atomic_write(runtime, target, "replacement", secret=True)
-            self.assertEqual(target.read_text(encoding="utf-8"), "original")
-            leaked = [path for path in Path(tmp).iterdir() if path.is_file() and path.read_text(encoding="utf-8") == "replacement"]
-            self.assertEqual(leaked, [])
-
-            unix = Runtime.create(home=Path(tmp), os_id="linux")
-            with patch("oneagent.installer.tempfile.NamedTemporaryFile", side_effect=OSError("disk full")):
-                with self.assertRaises(OneAgentError) as error:
-                    atomic_write(unix, Path(tmp) / "failed.txt", "value")
-            self.assertEqual(error.exception.code, "CONFIG_WRITE_FAILED")
-
-    def test_secret_backup_and_temporary_cleanup_failures_are_structured(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux")
-            target = Path(tmp) / ".oneagent" / "secret"
-            target.parent.mkdir()
-            target.write_text("old", encoding="utf-8")
-            real_secure_path = installer_module.secure_path
-
-            def fail_backup(runtime_arg, path, *, directory):
-                if ".backup-" in path.name:
-                    raise OneAgentError("CONFIG_WRITE_FAILED", "backup ACL failed")
-                return real_secure_path(runtime_arg, path, directory=directory)
-
-            with patch("oneagent.installer.secure_path", side_effect=fail_backup):
-                with self.assertRaisesRegex(OneAgentError, "backup ACL failed"):
-                    atomic_write(runtime, target, "new", secret=True)
-            self.assertEqual(list(target.parent.glob("secret.backup-*")), [])
-
-            with patch("oneagent.installer.secure_path", side_effect=fail_backup), patch.object(
-                Path,
-                "unlink",
-                side_effect=OSError("backup locked"),
-            ):
-                with self.assertRaisesRegex(OneAgentError, "Cannot remove insecure secret backup"):
-                    atomic_write(runtime, target, "new", secret=True)
-
-        for secret in [False, True]:
-            with self.subTest(secret=secret), tempfile.TemporaryDirectory() as tmp:
-                runtime = Runtime.create(home=Path(tmp), os_id="linux")
-                calls = 0
-
-                def fail_temporary(runtime_arg, path, *, directory):
-                    nonlocal calls
-                    calls += 1
-                    if calls == 2:
-                        raise OneAgentError("CONFIG_WRITE_FAILED", "temporary ACL failed")
-                    return real_secure_path(runtime_arg, path, directory=directory)
-
-                with patch("oneagent.installer.secure_path", side_effect=fail_temporary), patch.object(
-                    Path,
-                    "unlink",
-                    side_effect=OSError("temporary locked"),
-                ):
-                    expected = "temporary secret file" if secret else "temporary file"
-                    with self.assertRaisesRegex(OneAgentError, expected):
-                        atomic_write(runtime, Path(tmp) / ".oneagent" / "new", "value", secret=secret)
-
-    def test_install_requires_a_known_provider_and_preserves_explicit_base_override(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux", which=lambda _name: None)
-            with self.assertRaisesRegex(OneAgentError, "Provider must be"):
-                install_many(
-                    InstallOptions(
-                        agents=["codex"],
-                        provider="unknown",
-                        api_base_url="https://example.com/openai",
-                        api_key="key",
-                        skip_test=True,
-                    ),
-                    runtime,
-                )
-
-            install_many(
-                InstallOptions(
-                    agents=["codex"],
-                    provider="ppio",
-                    api_base_url="https://stale-custom.example.com/openai",
-                    api_key="key",
-                    skip_test=True,
-                ),
-                runtime,
-            )
-            config = (Path(tmp) / ".codex" / "config.toml").read_text(encoding="utf-8")
-            self.assertIn("https://stale-custom.example.com/openai", config)
-
-    def test_json_config_merge_and_validation(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            path = Path(tmp) / "config.json"
-            path.write_text("[]", encoding="utf-8")
-            with self.assertRaises(OneAgentError):
-                _load_json(path)
-            path.write_text("{", encoding="utf-8")
-            with self.assertRaises(OneAgentError):
-                _load_json(path)
-            path.write_text('{"keep":true,"provider":{"other":{}}}', encoding="utf-8")
-            runtime = Runtime.create(home=Path(tmp), os_id="linux")
-            meta = {"config_path": "config.json"}
-            write_openai_compatible_config(runtime, meta, "Provider", "https://example.com/openai", "model-a", "schema")
-            data = json.loads(path.read_text(encoding="utf-8"))
-            self.assertTrue(data["keep"])
-            self.assertIn("other", data["provider"])
-            self.assertEqual(data["model"], "oneagent/model-a")
-
-            path.write_text('{"env":[]}', encoding="utf-8")
-            with self.assertRaises(OneAgentError):
-                write_claude_config(runtime, {"config_path": "config.json"}, "https://example.com", "key", "model")
-            path.write_text('{"provider":[]}', encoding="utf-8")
-            with self.assertRaises(OneAgentError):
-                write_openai_compatible_config(runtime, meta, "Provider", "https://example.com/openai", "model-a", "schema")
-
-    def test_codex_toml_merge_preserves_unmanaged_settings(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux")
-            path = Path(tmp) / ".codex" / "config.toml"
-            path.parent.mkdir()
-            path.write_text(
-                'approval_policy = "on-request"\n'
-                'model_provider = "old"\n'
-                'model = "old-model"\n\n'
-                '[model_providers.old]\n'
-                'name = "Keep Me"\n\n'
-                '[model_providers.oneagent]\n'
-                'name = "Old OneAgent"\n'
-                'base_url = "https://old.example.com"\n',
-                encoding="utf-8",
-            )
-            write_codex_config(
-                runtime,
-                {"config_path": ".codex/config.toml"},
-                "PPIO",
-                "https://api.ppio.com/openai",
-                "model-a",
-            )
-            merged = tomllib.loads(path.read_text(encoding="utf-8"))
-            self.assertEqual(merged["approval_policy"], "on-request")
-            self.assertEqual(merged["model"], "model-a")
-            self.assertEqual(merged["model_providers"]["old"]["name"], "Keep Me")
-            self.assertEqual(merged["model_providers"]["oneagent"]["base_url"], "https://api.ppio.com/openai")
-
-            invalid = 'model = "unterminated\n'
-            path.write_text(invalid, encoding="utf-8")
-            with self.assertRaises(OneAgentError):
-                write_codex_config(runtime, {"config_path": ".codex/config.toml"}, "PPIO", "https://example.com", "m")
-            self.assertEqual(path.read_text(encoding="utf-8"), invalid)
-
-            path.write_text('model = "old"\n', encoding="utf-8")
-            with patch.object(Path, "read_text", side_effect=OSError("blocked")):
-                with self.assertRaisesRegex(OneAgentError, "Cannot read existing TOML"):
-                    write_codex_config(runtime, {"config_path": ".codex/config.toml"}, "PPIO", "https://example.com", "m")
-
-            for unsupported in [
-                '["model_providers"."oneagent"]\nname = "quoted table"\n',
-                '"model" = "quoted key"\n',
-            ]:
-                path.write_text(unsupported, encoding="utf-8")
-                with self.subTest(toml=unsupported), self.assertRaises(OneAgentError):
-                    write_codex_config(runtime, {"config_path": ".codex/config.toml"}, "PPIO", "https://example.com", "m")
-
-            with self.assertRaisesRegex(OneAgentError, "Cannot merge TOML"):
-                _merge_codex_toml('keep = true\n', 'model = "unterminated\n', path)
-
-    def test_windows_aider_config_and_unsupported_adapter(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runner = lambda args, **_kwargs: subprocess.CompletedProcess(args, 0, "", "")
-            runtime = Runtime.create(
-                home=Path(tmp),
-                os_id="windows",
-                runner=runner,
-                which=lambda name: "icacls.exe" if name == "icacls" else None,
-                env={"USERNAME": "tester"},
-            )
-            path = write_aider_config(
-                runtime,
-                {"config_path": ".oneagent/aider.env", "windows_config_path": ".oneagent/aider.ps1"},
-                "https://example.com/openai",
-                "key'quoted",
-            )
-            text = path.read_text(encoding="utf-8")
-            self.assertIn("$env:OPENAI_API_BASE", text)
-            self.assertIn("key''quoted", text)
-            with self.assertRaises(OneAgentError):
-                _write_agent_config(runtime, "unsupported", {"config_path": "x"}, "P", "https://example.com", "key", "m")
-
-    def test_version_and_install_manager_edges(self):
-        self.assertIsNone(_version_from_output("no version"))
-        meta = {"name": "Agent", "command": "agent", "version_args": ["--version"], "package": {"manager": "npm", "name": "agent", "version": "1.2.3"}}
-        runtime = Runtime.create(home=Path("/tmp"), os_id="linux", which=lambda name: "/bin/agent" if name == "agent" else "/bin/npm" if name == "npm" else None)
-        runtime.runner = lambda *_args, **_kwargs: (_ for _ in ()).throw(OSError("boom"))
-        self.assertIsNone(installed_version(runtime, meta))
-
-        runtime.runner = lambda args, **_kwargs: subprocess.CompletedProcess(args, 0, "Agent 1.2.3", "")
-        self.assertFalse(install_locked_agent(runtime, "agent", meta, enforce_locked=False, latest=False, timeout=1)["installed"])
-        self.assertFalse(install_locked_agent(runtime, "agent", meta, enforce_locked=True, latest=False, timeout=1)["installed"])
-
-        uv_meta = {"name": "Aider", "command": "", "package": {"manager": "uv", "name": "aider-chat", "version": "0.1.0"}}
-        uv_runtime = Runtime.create(
-            home=Path("/tmp"),
-            os_id="windows",
-            which=lambda name: {"uv": "uv.exe", "python3.12": "python3.12.exe"}.get(name),
-        )
-        calls = []
-        uv_runtime.runner = lambda args, **_kwargs: calls.append(args) or subprocess.CompletedProcess(args, 0, "", "")
-        result = install_locked_agent(uv_runtime, "aider", uv_meta, enforce_locked=False, latest=True, timeout=1)
-        self.assertTrue(result["installed"])
-        self.assertEqual(
-            calls[0],
-            [
-                "uv.exe",
-                "tool",
-                "install",
-                "--force",
-                "--python",
-                "python3.12.exe",
-                "--no-python-downloads",
-                "aider-chat",
-            ],
-        )
-        self.assertIsNone(result["version"])
-
-        with self.assertRaises(OneAgentError):
-            _python_312_for_uv(Runtime.create(home=Path("/tmp"), os_id="linux", which=lambda _name: None))
-        with self.assertRaisesRegex(OneAgentError, "uv is required"):
-            install_locked_agent(
-                Runtime.create(home=Path("/tmp"), os_id="linux", which=lambda _name: None),
-                "aider",
-                uv_meta,
-                enforce_locked=False,
-                latest=False,
-                timeout=1,
-            )
-        bad_meta = {"name": "Bad", "command": "", "package": {"manager": "curl", "name": "bad", "version": "1.0.0"}}
-        with self.assertRaises(OneAgentError):
-            install_locked_agent(runtime, "bad", bad_meta, enforce_locked=False, latest=False, timeout=1)
-
-    def test_uv_python_312_resolution_paths(self):
-        generic = Runtime.create(
-            home=Path("/tmp"),
-            os_id="linux",
-            which=lambda name: "/bin/python3" if name == "python3" else None,
-        )
-        generic.runner = lambda args, **_kwargs: subprocess.CompletedProcess(args, 0, "Python 3.12.9", "")
-        self.assertEqual(_python_312_for_uv(generic), "/bin/python3")
-
-        fallback = Runtime.create(
-            home=Path("/tmp"),
-            os_id="linux",
-            which=lambda name: {"python3": "/bin/python3", "python": "/bin/python"}.get(name),
-        )
-        fallback.runner = lambda args, **_kwargs: subprocess.CompletedProcess(
-            args,
-            1 if args[0] == "/bin/python3" else 0,
-            "Python 3.14.0" if args[0] == "/bin/python3" else "Python 3.12.8",
-            "",
-        )
-        self.assertEqual(_python_312_for_uv(fallback), "/bin/python")
-
-        windows = Runtime.create(
-            home=Path("C:/Users/Test"),
-            os_id="windows",
-            which=lambda name: {"python3": "python3.exe", "py": "py.exe"}.get(name),
-        )
-
-        def windows_runner(args, **_kwargs):
-            if args[0] == "python3.exe":
-                raise OSError("not runnable")
-            return subprocess.CompletedProcess(args, 0, "Python 3.12.7", "")
-
-        windows.runner = windows_runner
-        self.assertEqual(_python_312_for_uv(windows), "3.12")
-
-        windows.runner = lambda *_args, **_kwargs: (_ for _ in ()).throw(subprocess.TimeoutExpired("py", 1))
-        with self.assertRaises(OneAgentError):
-            _python_312_for_uv(windows)
-
-        no_launcher = Runtime.create(home=Path("C:/Users/Test"), os_id="windows", which=lambda _name: None)
-        with self.assertRaises(OneAgentError):
-            _python_312_for_uv(no_launcher)
-
-    def test_installer_timeout_oserror_and_nonzero(self):
-        meta = {"name": "Agent", "command": "", "package": {"manager": "npm", "name": "agent", "version": "1.0.0"}}
-        runtime = Runtime.create(home=Path("/tmp"), os_id="linux", which=lambda name: "/bin/npm" if name == "npm" else None)
-        for error, code in [(subprocess.TimeoutExpired("npm", 1), "TIMEOUT"), (OSError("boom"), "AGENT_INSTALL_FAILED")]:
-            runtime.runner = lambda *_args, error=error, **_kwargs: (_ for _ in ()).throw(error)
-            with self.subTest(code=code), self.assertRaises(OneAgentError) as raised:
-                install_locked_agent(runtime, "agent", meta, enforce_locked=False, latest=False, timeout=1)
-            self.assertEqual(raised.exception.code, code)
-        runtime.runner = lambda args, **_kwargs: subprocess.CompletedProcess(args, 9, "", "failed")
-        with self.assertRaises(OneAgentError) as raised:
-            install_locked_agent(runtime, "agent", meta, enforce_locked=False, latest=False, timeout=1)
-        self.assertEqual(raised.exception.code, "AGENT_INSTALL_FAILED")
-        self.assertIn("failed", raised.exception.message)
-
-        runtime.runner = lambda args, **_kwargs: subprocess.CompletedProcess(args, 9, "", "")
-        with self.assertRaises(OneAgentError) as empty_error:
-            install_locked_agent(runtime, "agent", meta, enforce_locked=False, latest=False, timeout=1)
-        self.assertEqual(empty_error.exception.message, "Installing Agent failed with exit code 9")
-
-        secret_runtime = Runtime.create(
-            home=Path("/tmp"),
-            os_id="linux",
-            which=lambda name: "/bin/npm" if name == "npm" else None,
-            env={"OPENAI_API_KEY": "sentinel-install-key"},
-        )
-        secret_runtime.runner = lambda args, **_kwargs: subprocess.CompletedProcess(
-            args,
-            7,
-            "",
-            "install failed for sentinel-install-key",
-        )
-        with self.assertRaises(OneAgentError) as secret_error:
-            install_locked_agent(secret_runtime, "agent", meta, enforce_locked=False, latest=False, timeout=1)
-        self.assertNotIn("sentinel-install-key", secret_error.exception.message)
-        self.assertIn("[redacted]", secret_error.exception.message)
-
-    def test_uv_install_hint_and_status_prerequisite_failure(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            missing = Runtime.create(home=Path(tmp), os_id="linux", which=lambda _name: None)
-            result = install_many(InstallOptions(agents=["aider"], configure=False), missing)
-            self.assertIn("uv tool install", result["log"])
-            self.assertIn("--no-python-downloads", result["log"])
-
-            uv_only = Runtime.create(
-                home=Path(tmp),
-                os_id="linux",
-                which=lambda name: "/bin/uv" if name == "uv" else None,
-            )
-            status = status_payload(uv_only)
-            self.assertFalse(status["agents"]["aider"]["canInstall"])
-
-            unsupported = {
-                "custom": {
-                    "name": "Custom",
-                    "group": "auto",
-                    "command": "custom",
-                    "config_mode": "auto",
-                    "config_path": ".custom/config",
-                    "platforms": ["linux"],
-                    "package": {"manager": "unsupported", "name": "custom", "version": "1.0.0"},
-                }
-            }
-            with patch("oneagent.installer.agent_catalog", return_value=unsupported):
-                unsupported_result = install_many(
-                    InstallOptions(agents=["custom"], configure=False),
-                    missing,
-                )
-            self.assertIn("Unsupported package manager", unsupported_result["log"])
-
-    def test_all_auto_config_adapters_and_check_only_paths(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            commands = {"codex": "/bin/codex", "claude": "/bin/claude", "opencode": "/bin/opencode", "kilo": "/bin/kilo", "aider": "/bin/aider"}
-            runtime = Runtime.create(home=Path(tmp), os_id="linux", which=lambda name: commands.get(name))
-            runtime.runner = lambda args, **_kwargs: subprocess.CompletedProcess(args, 0, "version 1.0.0", "")
-            result = install_many(
-                InstallOptions(
-                    agents=["codex", "claude-code", "opencode", "kilo-cli", "aider"],
-                    provider="ppio",
-                    api_key="secret",
-                    model="model-a",
-                    skip_test=True,
-                ),
-                runtime,
-            )
-            self.assertTrue(result["ok"])
-            self.assertEqual({item["status"] for item in result["results"]}, {"configured"})
-            claude = json.loads((Path(tmp) / ".claude" / "settings.json").read_text(encoding="utf-8"))
-            self.assertEqual(claude["env"]["ANTHROPIC_BASE_URL"], "https://api.ppio.com/anthropic")
-            self.assertEqual(claude["env"]["ANTHROPIC_SMALL_FAST_MODEL"], "model-a")
-            self.assertTrue((Path(tmp) / ".config" / "kilo" / "kilo.jsonc").exists())
-            self.assertTrue((Path(tmp) / ".oneagent" / "aider.env").exists())
-
-            checked = install_many(InstallOptions(agents=["codex"], configure=False, check_agent_only=True), runtime)
-            self.assertEqual(checked["results"][0]["status"], "installed")
-            missing_runtime = Runtime.create(home=Path(tmp), os_id="linux", which=lambda _name: None)
-            checked = install_many(InstallOptions(agents=["codex"], configure=False, check_agent_only=True), missing_runtime)
-            self.assertEqual(checked["results"][0]["status"], "skipped")
-
-    def test_claude_code_small_fast_model_is_optional_and_overrides(self):
-        # The fast/background model is an optional second field: empty follows the
-        # main model, a value overrides it. Both the settings.json the adapter
-        # writes and the native env file Claude Code actually reads must agree,
-        # or the Agent would run a different small model than the one configured.
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux", which=lambda name: {"claude": "/bin/claude"}.get(name))
-            runtime.runner = lambda args, **_kwargs: subprocess.CompletedProcess(args, 0, "version 1.0.0", "")
-
-            def small_fast():
-                settings = json.loads((Path(tmp) / ".claude" / "settings.json").read_text(encoding="utf-8"))
-                env_file = (Path(tmp) / ".oneagent" / "agents" / "claude-code.env").read_text(encoding="utf-8")
-                return settings["env"]["ANTHROPIC_SMALL_FAST_MODEL"], env_file
-
-            install_many(
-                InstallOptions(agents=["claude-code"], provider="ppio", api_key="secret", model="model-a", skip_test=True),
-                runtime,
-            )
-            value, env_file = small_fast()
-            self.assertEqual(value, "model-a")
-            self.assertIn("export ANTHROPIC_SMALL_FAST_MODEL=model-a", env_file)
-
-            install_many(
-                InstallOptions(
-                    agents=["claude-code"],
-                    provider="ppio",
-                    api_key="secret",
-                    model="model-a",
-                    small_fast_model="model-fast",
-                    skip_test=True,
-                ),
-                runtime,
-            )
-            value, env_file = small_fast()
-            self.assertEqual(value, "model-fast")
-            self.assertIn("export ANTHROPIC_SMALL_FAST_MODEL=model-fast", env_file)
-
-    def test_jsonc_comments_are_reported_as_comments_not_invalid_json(self):
-        # OpenCode and Kilo ship .jsonc, where comments are legal. OneAgent
-        # rewrites with json.dumps and cannot keep them, so it must refuse --
-        # but calling a valid JSONC file "invalid JSON" tells the user nothing
-        # actionable.
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            config = home / ".config" / "opencode" / "opencode.jsonc"
-            config.parent.mkdir(parents=True)
-            original = '{\n  // keep my own settings\n  "theme": "dark"\n}\n'
-            config.write_text(original, encoding="utf-8")
-            runtime = Runtime.create(home=home, os_id="linux", which=lambda _name: None)
-            probe = {"ok": True, "message": "ok", "error_code": None, "retryable": False, "protocol": "openai"}
-            with patch("oneagent.installer.protocol_probe", return_value=probe):
-                result = install_many(
-                    InstallOptions(agents=["opencode"], api_key="k", model="m"), runtime
-                )
-            failure = result["results"][0]
-            self.assertEqual(failure["error_code"], "CONFIG_WRITE_FAILED")
-            self.assertIn("JSONC comments", failure["message"])
-            # The user's file must survive untouched.
-            self.assertEqual(config.read_text(encoding="utf-8"), original)
-
-            # A .jsonc that is broken for some other reason keeps the generic message.
-            config.write_text('{"theme": "dark",,}', encoding="utf-8")
-            with patch("oneagent.installer.protocol_probe", return_value=probe):
-                result = install_many(
-                    InstallOptions(agents=["opencode"], api_key="k", model="m"), runtime
-                )
-            self.assertIn("invalid", result["results"][0]["message"])
-            self.assertNotIn("JSONC comments", result["results"][0]["message"])
-
-            # An existing but empty config is a fresh start, not a parse error.
-            config.write_text("   \n", encoding="utf-8")
-            with patch("oneagent.installer.protocol_probe", return_value=probe):
-                result = install_many(
-                    InstallOptions(agents=["opencode"], api_key="k", model="m"), runtime
-                )
-            self.assertEqual(result["results"][0]["status"], "configured")
-            self.assertEqual(json.loads(config.read_text(encoding="utf-8"))["model"], "oneagent/m")
-
-    def test_protocol_mismatch_refuses_to_write_agent_config(self):
-        # A model that answers Chat Completions can still reject Responses. If
-        # OneAgent wrote the Codex config anyway, the failure would surface as an
-        # opaque error inside Codex on the user's first real request.
-        unsupported = {
-            "ok": False,
-            "reachable": True,
-            "protocol": "responses",
-            "status": 400,
-            "message": "Model 'glm-5.2' does not support OpenAI Responses.",
-            "error_code": "PROTOCOL_UNSUPPORTED",
-            "retryable": False,
-        }
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            runtime = Runtime.create(home=home, os_id="linux", which=lambda _name: None)
-            with patch("oneagent.installer.protocol_probe", return_value=unsupported), patch(
-                "oneagent.installer.list_models", return_value={"ok": False, "models": []}
-            ):
-                result = install_many(
-                    InstallOptions(agents=["codex"], api_key="key", model="glm-5.2"), runtime
-                )
-        self.assertFalse(result["ok"])
-        self.assertEqual(result["results"][0]["error_code"], "PROTOCOL_UNSUPPORTED")
-        self.assertFalse(result["results"][0]["retryable"])
-        self.assertEqual(result["code"], 7)
-        self.assertFalse((home / ".codex" / "config.toml").exists())
-        self.assertFalse((home / ".oneagent" / "profile.json").exists())
-
-    def test_each_agent_is_probed_over_its_own_protocol(self):
-        seen: list[str] = []
-
-        def fake_probe(*, protocol, **_kwargs):
-            seen.append(protocol)
-            return {"ok": True, "message": "ok", "error_code": None, "retryable": False, "protocol": protocol}
-
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux", which=lambda _name: None)
-            with patch("oneagent.installer.protocol_probe", side_effect=fake_probe):
-                result = install_many(
-                    InstallOptions(
-                        agents=["codex", "claude-code", "opencode"], api_key="key", model="m"
-                    ),
-                    runtime,
-                )
-        # Codex speaks Responses, Claude Code speaks Anthropic Messages, OpenCode
-        # speaks Chat Completions; shared protocols are probed once.
-        self.assertEqual(sorted(seen), ["anthropic", "openai", "responses"])
-        self.assertEqual(sorted(result["probes"]), ["anthropic", "openai", "responses"])
-        self.assertTrue(result["ok"])
-
-    def test_status_payload_can_install_edges(self):
-        # On Windows, claude-code additionally requires git; both sides of that
-        # `and` need exercising or the branch report stays partial.
-        tools = {"npm": r"C:\node\npm.cmd", "git": r"C:\git\git.exe"}
-        with_tools = Runtime.create(
-            home=Path("/tmp"), os_id="windows", which=lambda name: tools.get(name)
-        )
-        self.assertTrue(status_payload(with_tools)["capabilities"]["canInstall"]["claude-code"])
-        without_tools = Runtime.create(home=Path("/tmp"), os_id="windows", which=lambda _name: None)
-        self.assertFalse(status_payload(without_tools)["capabilities"]["canInstall"]["claude-code"])
-
-        # An OS no Agent declares support for must not claim any compatibility.
-        unknown_os = Runtime.create(home=Path("/tmp"), os_id="freebsd", which=lambda _name: None)
-        self.assertEqual(status_payload(unknown_os)["capabilities"]["supportedAgentIds"], [])
-
-    def test_unknown_model_is_relabeled_from_model_discovery(self):
-        # Endpoints refuse an unknown model with the same shapes they use for
-        # an unsupported protocol, so a bare probe verdict reads "model does
-        # not support <protocol>". When discovery works, the verdict must name
-        # the real problem and show valid IDs instead.
-        refused = {
-            "ok": False,
-            "reachable": True,
-            "protocol": "responses",
-            "status": 404,
-            "message": "Model 'no-such' does not support OpenAI Responses.",
-            "error_code": "PROTOCOL_UNSUPPORTED",
-            "retryable": False,
-        }
-        listing = {"ok": True, "models": ["gpt-5.6-terra", "qwen3-coder", "model-a", "model-b", "model-c", "model-d"]}
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            runtime = Runtime.create(home=home, os_id="linux", which=lambda _name: None)
-            with (
-                patch("oneagent.installer.protocol_probe", return_value=refused),
-                patch("oneagent.installer.list_models", return_value=listing) as discovery,
-            ):
-                result = install_many(
-                    InstallOptions(agents=["codex"], api_key="key", model="no-such"), runtime
-                )
-        discovery.assert_called_once()
-        failure = result["results"][0]
-        self.assertEqual(failure["error_code"], "MODELS_UNSUPPORTED")
-        self.assertEqual(result["code"], 6)
-        self.assertIn("'no-such'", failure["message"])
-        self.assertIn("gpt-5.6-terra", failure["message"])
-        # The sample is capped so a huge model list cannot flood the message.
-        self.assertNotIn("model-d", failure["message"])
-        self.assertFalse((home / ".codex" / "config.toml").exists())
-
-    def test_model_discovery_doubt_keeps_the_probe_verdict(self):
-        # Discovery needs the network too. When it fails, finds nothing, or
-        # lists the model, "wrong model" cannot be told from "unreachable
-        # endpoint" or a genuine protocol gap -- so the original verdict stands.
-        refused = {
-            "ok": False,
-            "reachable": False,
-            "protocol": "openai",
-            "status": 0,
-            "message": "Cannot reach endpoint: connection refused",
-            "error_code": "PROVIDER_UNREACHABLE",
-            "retryable": True,
-        }
-        cases = [
-            {"ok": False, "models": []},          # discovery itself failed
-            {"ok": True, "models": []},           # endpoint lists no models
-            {"ok": True, "models": ["model-a"]},  # model IS listed: not a typo
-        ]
-        for listing in cases:
-            with self.subTest(listing=listing):
-                with tempfile.TemporaryDirectory() as tmp:
-                    runtime = Runtime.create(home=Path(tmp), os_id="linux", which=lambda _name: None)
-                    with (
-                        patch("oneagent.installer.protocol_probe", return_value=dict(refused)),
-                        patch("oneagent.installer.list_models", return_value=listing),
-                    ):
-                        result = install_many(
-                            InstallOptions(agents=["opencode"], api_key="key", model="model-a"), runtime
-                        )
-                self.assertEqual(result["results"][0]["error_code"], "PROVIDER_UNREACHABLE")
-                self.assertTrue(result["results"][0]["retryable"])
-
-    def test_model_discovery_is_skipped_when_every_probe_passed(self):
-        probe = {"ok": True, "message": "ok", "error_code": None, "retryable": False, "protocol": "openai"}
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux", which=lambda _name: None)
-            with (
-                patch("oneagent.installer.protocol_probe", return_value=probe),
-                patch("oneagent.installer.list_models", side_effect=AssertionError("discovery must not run")),
-            ):
-                result = install_many(
-                    InstallOptions(agents=["opencode"], api_key="key", model="model-a"), runtime
-                )
-        self.assertTrue(result["ok"])
-
-    def test_install_validation_platform_probe_and_windows_next_steps(self):
-        runtime = Runtime.create(home=Path("/tmp"), os_id="linux", which=lambda _name: None)
-        with self.assertRaises(OneAgentError):
-            install_many(InstallOptions(agents=[]), runtime)
-        with self.assertRaises(OneAgentError):
-            install_many(InstallOptions(agents=["unknown"], configure=False), runtime)
-        with self.assertRaises(OneAgentError):
-            install_many(InstallOptions(agents=["codex"], profile_agents=["opencode"], configure=False), runtime)
-        with self.assertRaises(OneAgentError):
-            install_many(InstallOptions(agents=["codex"], timeout=0), runtime)
-        with self.assertRaises(OneAgentError):
-            install_many(InstallOptions(agents=["codex"], api_key="", configure=True), runtime)
-
-        unsupported = {"agent": {"name": "Agent", "group": "auto", "command": "", "config_mode": "auto", "config_path": "x", "platforms": []}}
-        with patch("oneagent.installer.agent_catalog", return_value=unsupported):
-            result = install_many(InstallOptions(agents=["agent"], configure=False), runtime)
-        self.assertEqual(result["results"][0]["error_code"], "PREREQUISITE_MISSING")
-
-        with tempfile.TemporaryDirectory() as tmp, patch(
-            "oneagent.installer.protocol_probe",
-            return_value={"ok": False, "message": "provider failed", "error_code": "PROVIDER_UNREACHABLE", "retryable": True},
-        ), patch("oneagent.installer.list_models", return_value={"ok": False, "models": []}):
-            result = install_many(InstallOptions(agents=["codex"], api_key="key", model="m"), Runtime.create(home=Path(tmp), os_id="linux", which=lambda _name: None))
-        self.assertFalse(result["ok"])
-        self.assertIn("provider failed", result["log"])
-
-        with tempfile.TemporaryDirectory() as tmp, patch(
-            "oneagent.installer.protocol_probe",
-            return_value={"ok": True, "message": "ok", "error_code": None, "retryable": False},
-        ):
-            successful_probe = install_many(
-                InstallOptions(agents=["codex"], api_key="key", model="m"),
-                Runtime.create(home=Path(tmp), os_id="linux", which=lambda _name: None),
-            )
-        self.assertTrue(successful_probe["ok"])
-        self.assertTrue(successful_probe["probe"]["ok"])
-
-        with tempfile.TemporaryDirectory() as tmp:
-            failing_runtime = Runtime.create(home=Path(tmp), os_id="linux", which=lambda name: "/fake/npm" if name == "npm" else None)
-            failing_runtime.runner = lambda args, **_kwargs: subprocess.CompletedProcess(args, 9, "", "failed")
-            with patch("oneagent.installer.protocol_probe", return_value={"ok": False, "message": "provider failed", "error_code": "PROVIDER_UNREACHABLE", "retryable": True}):
-                result = install_many(
-                    InstallOptions(agents=["codex"], api_key="key", install_agent=True, skip_test=False),
-                    failing_runtime,
-                )
-            self.assertEqual(result["code"], 4)
-
-        with tempfile.TemporaryDirectory() as tmp, patch("oneagent.installer._next_step", return_value=""):
-            no_next = install_many(
-                InstallOptions(agents=["codex"], configure=False),
-                Runtime.create(home=Path(tmp), os_id="linux", which=lambda _name: None),
-            )
-            self.assertEqual(no_next["next"], "")
-
-        windows = Runtime.create(home=Path("C:/Users/Test"), os_id="windows")
-        self.assertIn("env.ps1", _next_step(windows, "codex", "m"))
-        self.assertIn("aider.ps1", _next_step(windows, "aider", "m"))
-        self.assertEqual(_next_step(windows, "unknown", "m"), "")
-
-        windows_status_runtime = Runtime.create(
-            home=Path("C:/Users/Test"),
-            os_id="windows",
-            which=lambda name: f"C:/{name}.exe" if name in {"npm", "python", "git", "claude"} else None,
-        )
-        status = status_payload(windows_status_runtime)
-        self.assertTrue(status["agents"]["claude-code"]["canInstall"])
-
-        limited_catalog = {
-            "limited": {
-                "name": "Limited",
-                "group": "guide",
-                "command": "",
-                "config_mode": "guide",
-                "platforms": ["linux"],
-                "guide": "guide",
-            }
-        }
-        with patch("oneagent.installer.agent_catalog", return_value=limited_catalog), patch("oneagent.installer.public_catalog", return_value=[]):
-            limited = status_payload(Runtime.create(home=Path("C:/Users/Test"), os_id="windows", which=lambda _name: None))
-        self.assertEqual(limited["capabilities"]["supportedAgentIds"], [])
-
-
-if __name__ == "__main__":
-    unittest.main()
diff --git a/tests/test_install_contract.py b/tests/test_install_contract.py
deleted file mode 100644
index ce8eb9de..00000000
--- a/tests/test_install_contract.py
+++ /dev/null
@@ -1,717 +0,0 @@
-"""Contracts for the real installation path.
-
-Every other suite replaces Runtime.runner and never looks at the command it was
-handed, so the argv that actually installs an Agent was unverified: a lock entry
-could lose its version and every test would still pass. These assert on the
-command instead of executing it, which keeps them offline and instant.
-"""
-
-from __future__ import annotations
-
-import json
-import subprocess
-import tempfile
-import unittest
-from pathlib import Path
-
-from oneagent.catalog import (
-    OFFICIAL_NPM_REGISTRY,
-    PACKAGE_MIRRORS,
-    agent_catalog,
-    public_mirrors,
-)
-from oneagent.errors import OneAgentError
-from oneagent.installer import (
-    InstallOptions,
-    Runtime,
-    _next_step,
-    _restart_hint,
-    install_locked_agent,
-    install_many,
-    needs_env_file,
-    resolve_registry,
-    write_agent_env,
-)
-
-
-class RecordingRunner:
-    """Captures argv and env, and answers --version and npm view from a table.
-
-    The integrity check runs `npm view <spec> dist.integrity` before installing,
-    so a runner that answers everything with a generic success would fail that
-    check instead of reaching the install.
-    """
-
-    def __init__(
-        self,
-        versions: dict[str, str] | None = None,
-        returncode: int = 0,
-        integrity: str | None = None,
-        integrity_returncode: int = 0,
-    ) -> None:
-        self.calls: list[list[str]] = []
-        self.envs: list[dict[str, str]] = []
-        self.versions = versions or {}
-        self.returncode = returncode
-        self.integrity = integrity
-        self.integrity_returncode = integrity_returncode
-
-    def __call__(self, args, **kwargs):  # noqa: ANN001 - mirrors subprocess.run
-        argv = [str(item) for item in args]
-        self.calls.append(argv)
-        self.envs.append(dict(kwargs.get("env") or {}))
-        if "view" in argv and "dist.integrity" in argv:
-            if self.integrity_returncode:
-                return subprocess.CompletedProcess(argv, self.integrity_returncode, "", "not found")
-            # Default to whatever the manifest holds, so a test that is not
-            # about integrity does not have to restate the hash.
-            reported = self.integrity if self.integrity is not None else self._manifest_integrity(argv)
-            return subprocess.CompletedProcess(argv, 0, f"{reported}\n", "")
-        for command, version in self.versions.items():
-            if argv[0].endswith(command) and "--version" in argv:
-                return subprocess.CompletedProcess(argv, 0, f"{command} {version}\n", "")
-        if "install" in argv:
-            return subprocess.CompletedProcess(argv, self.returncode, "", "boom" if self.returncode else "")
-        return subprocess.CompletedProcess(argv, 0, "", "")
-
-    @staticmethod
-    def _manifest_integrity(argv: list[str]) -> str:
-        spec = argv[2]
-        name = spec.rsplit("@", 1)[0]
-        for meta in agent_catalog().values():
-            package = meta.get("package") or {}
-            if package.get("name") == name:
-                return str(package.get("integrity", ""))
-        return ""
-
-    @property
-    def install_calls(self) -> list[list[str]]:
-        return [call for call in self.calls if "install" in call]
-
-    @property
-    def registries(self) -> list[str]:
-        return [env["npm_config_registry"] for env in self.envs if "npm_config_registry" in env]
-
-
-def runtime_with(
-    *,
-    runner: RecordingRunner,
-    present: set[str] | None = None,
-    os_id: str = "linux",
-    env: dict[str, str] | None = None,
-) -> Runtime:
-    available = {"npm", "uv", "python3.12"} if present is None else present
-    return Runtime(
-        home=Path("/tmp/oneagent-contract"),
-        os_id=os_id,
-        runner=runner,
-        which=lambda name: f"/usr/bin/{name}" if name in available else None,
-        env=env if env is not None else {},
-    )
-
-
-class InstallCommandTests(unittest.TestCase):
-    """The two Agents this verification covers, plus the uv outlier."""
-
-    def install(self, agent_id: str, runtime: Runtime, **kwargs):
-        result = install_locked_agent(
-            runtime,
-            agent_id,
-            agent_catalog()[agent_id],
-            enforce_locked=kwargs.pop("enforce_locked", True),
-            latest=kwargs.pop("latest", False),
-            timeout=kwargs.pop("timeout", 180),
-        )
-        return result
-
-    def test_installs_the_version_the_lock_manifest_names(self):
-        # The version must come from the manifest, so bumping the lock is enough
-        # to change what gets installed and a hardcoded version cannot drift.
-        catalog = agent_catalog()
-        for agent_id in ("codex", "claude-code"):
-            with self.subTest(agent=agent_id):
-                package = catalog[agent_id]["package"]
-                runner = RecordingRunner()
-                result = self.install(agent_id, runtime_with(runner=runner, present={"npm"}))
-                self.assertEqual(
-                    runner.install_calls[0],
-                    ["/usr/bin/npm", "install", "-g", f"{package['name']}@{package['version']}"],
-                )
-                self.assertTrue(result["installed"])
-                self.assertEqual(result["version"], package["version"])
-
-    def test_pinned_by_default_and_floating_only_when_asked(self):
-        # A spec without @version is what "latest" means; it must never be the
-        # default, since the whole premise of the lock manifest is pinning.
-        pinned = RecordingRunner()
-        self.install("codex", runtime_with(runner=pinned, present={"npm"}))
-        locked = agent_catalog()["codex"]["package"]["version"]
-        self.assertEqual(pinned.install_calls[0][-1], f"@openai/codex@{locked}")
-
-        floating = RecordingRunner()
-        self.install("codex", runtime_with(runner=floating, present={"npm"}), latest=True)
-        self.assertEqual(floating.install_calls[0][-1], "@openai/codex")
-
-    def test_already_at_the_locked_version_installs_nothing(self):
-        catalog = agent_catalog()
-        locked = catalog["codex"]["package"]["version"]
-        runner = RecordingRunner(versions={"codex": locked})
-        result = self.install("codex", runtime_with(runner=runner, present={"npm", "codex"}))
-        self.assertEqual(runner.install_calls, [])
-        self.assertFalse(result["installed"])
-        self.assertEqual(result["version"], locked)
-
-    def test_an_older_installation_is_upgraded_to_the_locked_version(self):
-        catalog = agent_catalog()
-        locked = catalog["codex"]["package"]["version"]
-        runner = RecordingRunner(versions={"codex": "0.0.1"})
-        result = self.install("codex", runtime_with(runner=runner, present={"npm", "codex"}))
-        self.assertEqual(runner.install_calls[0][-1], f"@openai/codex@{locked}")
-        self.assertTrue(result["installed"])
-
-    def test_an_existing_install_is_left_alone_when_the_lock_is_not_enforced(self):
-        runner = RecordingRunner(versions={"codex": "0.0.1"})
-        result = self.install(
-            "codex", runtime_with(runner=runner, present={"npm", "codex"}), enforce_locked=False
-        )
-        self.assertEqual(runner.install_calls, [])
-        self.assertEqual(result["version"], "0.0.1")
-
-    def test_aider_uses_uv_with_an_existing_python_and_no_downloads(self):
-        # Aider is the one uv package; --no-python-downloads is a product
-        # promise (OneAgent never fetches a Python runtime behind the user).
-        runner = RecordingRunner()
-        self.install("aider", runtime_with(runner=runner, present={"uv", "python3.12"}))
-        argv = runner.install_calls[0]
-        self.assertEqual(argv[:4], ["/usr/bin/uv", "tool", "install", "--force"])
-        self.assertIn("--no-python-downloads", argv)
-        self.assertTrue(argv[-1].startswith("aider-chat=="))
-
-
-class CredentialDeliveryTests(unittest.TestCase):
-    """Every auto Agent must have a credential route that actually works.
-
-    Claude Code was reported as `configured` while starting with "Not logged in":
-    its credential went only into settings.json, which it ignores. Nothing in the
-    suite could see that, because no test asked how a credential was supposed to
-    reach an Agent -- only that a file had been written.
-    """
-
-    def configure(self, tmp: str, agents: list[str], *, model: str = "m"):
-        runtime = Runtime(
-            home=Path(tmp),
-            os_id="linux",
-            runner=RecordingRunner(),
-            which=lambda name: f"/usr/bin/{name}",
-            env={},
-        )
-        result = install_many(
-            InstallOptions(
-                agents=agents,
-                provider="ppio",
-                api_key="K-DELIVERY",
-                model=model,
-                configure=True,
-                skip_test=True,
-                home=Path(tmp),
-                os_id="linux",
-            ),
-            runtime,
-        )
-        self.assertTrue(result["ok"], result)
-        return result
-
-    def test_every_auto_agent_declares_how_its_credential_arrives(self):
-        # An Agent with no declaration silently gets no env file, which is the
-        # exact shape of the Claude Code defect.
-        for agent_id, meta in agent_catalog().items():
-            if meta.get("config_mode") != "auto":
-                continue
-            with self.subTest(agent=agent_id):
-                self.assertIn(
-                    meta.get("credential_delivery"),
-                    {"oneagent_env", "native_env", "config_file"},
-                    f"{agent_id} does not declare credential_delivery",
-                )
-
-    def test_an_agent_reading_only_its_own_variables_gets_them(self):
-        # Claude Code is this case. The env file has to define the names the
-        # Agent itself reads, not just OneAgent's own.
-        with tempfile.TemporaryDirectory() as tmp:
-            self.configure(tmp, ["claude-code"], model="claude-model")
-            env_file = Path(tmp) / ".oneagent" / "agents" / "claude-code.env"
-            self.assertTrue(env_file.is_file(), "claude-code got no env file")
-            content = env_file.read_text(encoding="utf-8")
-            declared = agent_catalog()["claude-code"]["env_vars"]
-            for name in declared.values():
-                self.assertIn(f"export {name}=", content, f"{name} missing from the env file")
-            self.assertIn("K-DELIVERY", content)
-            self.assertIn("claude-model", content)
-
-    def test_the_start_command_sources_the_file_holding_the_credential(self):
-        # Telling the user to run plain `claude` while the credential sits in a
-        # file nothing sources is how the original defect reached them.
-        with tempfile.TemporaryDirectory() as tmp:
-            result = self.configure(tmp, ["claude-code"])
-            self.assertIn("source ~/.oneagent/agents/claude-code.env", result["next"])
-            self.assertIn("claude", result["next"])
-
-    def test_each_auto_agent_has_a_credential_route_after_configuring(self):
-        # The general form of the defect: for every Agent, the key must be
-        # reachable either from its env file or from the config the adapter
-        # wrote. Neither means the Agent cannot authenticate.
-        catalog = agent_catalog()
-        auto = [agent for agent, meta in catalog.items() if meta.get("config_mode") == "auto"]
-        with tempfile.TemporaryDirectory() as tmp:
-            self.configure(tmp, auto)
-            home = Path(tmp)
-            for agent_id in auto:
-                with self.subTest(agent=agent_id):
-                    meta = catalog[agent_id]
-                    env_file = home / ".oneagent" / "agents" / f"{agent_id}.env"
-                    config_path = meta.get("config_path")
-                    holders = []
-                    if env_file.is_file() and "K-DELIVERY" in env_file.read_text(encoding="utf-8"):
-                        holders.append("env file")
-                    if config_path:
-                        config = home / str(config_path)
-                        if config.is_file() and "K-DELIVERY" in config.read_text(encoding="utf-8"):
-                            holders.append("config file")
-                    self.assertTrue(holders, f"{agent_id} has no route to its credential")
-
-    def test_an_agent_whose_credential_lives_in_its_config_gets_no_env_file(self):
-        # Aider's config is itself a shell script holding the key, so a second
-        # file would duplicate the secret for nothing.
-        self.assertFalse(needs_env_file(agent_catalog()["aider"]))
-        with tempfile.TemporaryDirectory() as tmp:
-            self.configure(tmp, ["aider"])
-            self.assertFalse((Path(tmp) / ".oneagent" / "agents" / "aider.env").exists())
-            self.assertIn("K-DELIVERY", (Path(tmp) / ".oneagent" / "aider.env").read_text(encoding="utf-8"))
-
-    def test_the_credential_file_is_private(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            self.configure(tmp, ["claude-code"])
-            env_file = Path(tmp) / ".oneagent" / "agents" / "claude-code.env"
-            self.assertEqual(env_file.stat().st_mode & 0o777, 0o600)
-
-    def test_a_declared_variable_with_no_value_is_omitted_not_written_empty(self):
-        # An empty ANTHROPIC_MODEL is worse than an absent one: the Agent would
-        # read the blank and refuse the request rather than fall back.
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime(
-                home=Path(tmp),
-                os_id="linux",
-                runner=RecordingRunner(),
-                which=lambda name: f"/usr/bin/{name}",
-                env={},
-            )
-            write_agent_env(
-                runtime,
-                "claude-code",
-                "K-NOMODEL",
-                "https://example.com/anthropic",
-                meta=agent_catalog()["claude-code"],
-                model="",
-            )
-            content = (Path(tmp) / ".oneagent" / "agents" / "claude-code.env").read_text(encoding="utf-8")
-            self.assertIn("export ANTHROPIC_AUTH_TOKEN=", content)
-            self.assertNotIn("ANTHROPIC_MODEL=", content)
-            self.assertNotIn("ANTHROPIC_SMALL_FAST_MODEL=", content)
-
-    def test_an_agent_with_no_declared_variables_gets_only_the_oneagent_names(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime(
-                home=Path(tmp),
-                os_id="linux",
-                runner=RecordingRunner(),
-                which=lambda name: f"/usr/bin/{name}",
-                env={},
-            )
-            write_agent_env(
-                runtime, "codex", "K-CODEX", "https://example.com/openai", meta=agent_catalog()["codex"]
-            )
-            content = (Path(tmp) / ".oneagent" / "agents" / "codex.env").read_text(encoding="utf-8")
-            self.assertIn("export ONEAGENT_API_KEY_CODEX=", content)
-            self.assertNotIn("ANTHROPIC_", content)
-
-
-class StartAndRestartHintTests(unittest.TestCase):
-    """The hints have to name a command that exists and source what holds the key."""
-
-    def hints(self, agent_id: str, os_id: str = "linux", model: str = "m") -> tuple[str, str]:
-        runtime = Runtime(
-            home=Path("/tmp/oneagent-hints"),
-            os_id=os_id,
-            runner=RecordingRunner(),
-            which=lambda name: f"/usr/bin/{name}",
-            env={},
-        )
-        return _next_step(runtime, agent_id, model), _restart_hint(agent_id)
-
-    def test_every_auto_agent_gets_a_start_command_naming_its_own_binary(self):
-        # Derived from the manifest, so a renamed command cannot leave a stale
-        # instruction behind in the code.
-        for agent_id, meta in agent_catalog().items():
-            if meta.get("config_mode") != "auto":
-                continue
-            with self.subTest(agent=agent_id):
-                start, restart = self.hints(agent_id)
-                self.assertIn(str(meta["command"]), start)
-                self.assertIn(str(meta["command"]), restart)
-
-    def test_an_agent_needing_an_env_file_is_told_to_source_it_in_both_hints(self):
-        for agent_id in ("codex", "claude-code", "opencode", "kilo-cli"):
-            with self.subTest(agent=agent_id):
-                start, restart = self.hints(agent_id)
-                self.assertIn(f"~/.oneagent/agents/{agent_id}.env", start)
-                self.assertIn(f"~/.oneagent/agents/{agent_id}.env", restart)
-
-    def test_windows_uses_its_own_shell_syntax(self):
-        start, _ = self.hints("claude-code", os_id="windows")
-        self.assertIn("agents\\claude-code.env.ps1", start)
-        self.assertIn(";", start)
-        aider_start, _ = self.hints("aider", os_id="windows")
-        self.assertIn("aider.ps1", aider_start)
-        self.assertIn("--model openai/m", aider_start)
-
-    def test_aider_sources_its_config_script_and_passes_the_model(self):
-        start, restart = self.hints("aider")
-        self.assertIn("source ~/.oneagent/aider.env", start)
-        self.assertIn("--model openai/m", start)
-        self.assertIn("aider.env", restart)
-
-    def test_a_guide_only_or_unknown_agent_gets_no_start_command(self):
-        self.assertEqual(self.hints("cursor")[0], "")
-        self.assertEqual(self.hints("brand-new-agent")[0], "")
-        # A restart hint still has to say something actionable.
-        self.assertIn("brand-new-agent", self.hints("brand-new-agent")[1])
-
-
-class RegistryTests(unittest.TestCase):
-    """An authorised mirror changes where a package comes from, nothing else."""
-
-    def install(self, runtime: Runtime, agent_id: str = "codex", **kwargs):
-        return install_locked_agent(
-            runtime,
-            agent_id,
-            agent_catalog()[agent_id],
-            enforce_locked=True,
-            latest=kwargs.pop("latest", False),
-            timeout=180,
-            registry=kwargs.pop("registry", ""),
-        )
-
-    def test_the_official_registry_is_the_default_and_sets_nothing(self):
-        # A mirror must always be an explicit choice: switching automatically
-        # would leave the user unable to tell where a package came from.
-        runner = RecordingRunner()
-        result = self.install(runtime_with(runner=runner, present={"npm"}))
-        self.assertEqual(runner.registries, [])
-        self.assertEqual(result["registry"], OFFICIAL_NPM_REGISTRY)
-
-    def test_a_named_mirror_reaches_npm_through_its_environment(self):
-        runner = RecordingRunner()
-        result = self.install(runtime_with(runner=runner, present={"npm"}), registry="npmmirror")
-        expected = PACKAGE_MIRRORS["npmmirror"]["registry"]
-        self.assertEqual(result["registry"], expected)
-        self.assertTrue(runner.registries)
-        self.assertTrue(all(value == expected for value in runner.registries))
-        # The command itself is unchanged: the pinned spec still governs.
-        locked = agent_catalog()["codex"]["package"]["version"]
-        self.assertEqual(runner.install_calls[0][-1], f"@openai/codex@{locked}")
-
-    def test_an_explicit_https_url_is_accepted_and_normalised(self):
-        self.assertEqual(resolve_registry("https://npm.example.com"), "https://npm.example.com/")
-        self.assertEqual(resolve_registry("https://npm.example.com/"), "https://npm.example.com/")
-        self.assertEqual(resolve_registry(""), OFFICIAL_NPM_REGISTRY)
-        self.assertEqual(resolve_registry("official"), OFFICIAL_NPM_REGISTRY)
-
-    def test_plaintext_and_malformed_registries_are_refused(self):
-        # A registry URL lands in the installer environment and the install log,
-        # so http:// and embedded credentials are both unacceptable.
-        for value in [
-            "http://npm.example.com",
-            "ftp://npm.example.com",
-            "https://user:pass@npm.example.com",
-            "https://",
-            "not-a-url",
-            "https://npm.example.com/\nX",
-        ]:
-            with self.subTest(registry=value):
-                with self.assertRaises(OneAgentError) as caught:
-                    resolve_registry(value)
-                self.assertEqual(caught.exception.code, "INVALID_REQUEST")
-
-    def test_every_declared_mirror_records_its_upstream_and_uses_https(self):
-        # The product boundary admits a mirror only with a licence, a pinned
-        # version, a checksum and an upstream address; the first and last are
-        # this table's responsibility.
-        for mirror_id, meta in PACKAGE_MIRRORS.items():
-            with self.subTest(mirror=mirror_id):
-                self.assertTrue(str(meta["registry"]).startswith("https://"))
-                self.assertTrue(str(meta["upstream"]).startswith("https://"))
-                self.assertTrue(meta["note"])
-                self.assertTrue(meta["name"])
-
-    def test_the_ui_sees_each_mirror_with_its_upstream(self):
-        # The UI has to be able to show where a package comes from, so the
-        # projection may not drop the upstream address.
-        published = public_mirrors()
-        self.assertEqual({item["id"] for item in published}, set(PACKAGE_MIRRORS))
-        for item in published:
-            with self.subTest(mirror=item["id"]):
-                self.assertTrue(item["upstream"].startswith("https://"))
-                self.assertTrue(item["registry"].startswith("https://"))
-                self.assertTrue(item["note"])
-
-    def test_no_mirror_points_at_storage_oneagent_operates(self):
-        # Redistributing a proprietary Agent needs a licence that pointing at a
-        # public read-only mirror does not, so a mirror may never be ours.
-        for mirror_id, meta in PACKAGE_MIRRORS.items():
-            with self.subTest(mirror=mirror_id):
-                host = str(meta["registry"]).lower()
-                for forbidden in ("oneagent", "maimory"):
-                    self.assertNotIn(forbidden, host)
-
-
-class IntegrityTests(unittest.TestCase):
-    def install(self, runtime: Runtime, agent_id: str = "codex", **kwargs):
-        return install_locked_agent(
-            runtime,
-            agent_id,
-            agent_catalog()[agent_id],
-            enforce_locked=True,
-            latest=kwargs.pop("latest", False),
-            timeout=180,
-            registry=kwargs.pop("registry", ""),
-        )
-
-    def test_the_manifest_checksum_is_checked_before_installing(self):
-        # Recorded in the lock manifest but never read until now: the version was
-        # pinned and the bytes were not.
-        for agent_id in ("codex", "claude-code"):
-            with self.subTest(agent=agent_id):
-                runner = RecordingRunner()
-                self.install(runtime_with(runner=runner, present={"npm"}), agent_id)
-                view = [call for call in runner.calls if "view" in call]
-                self.assertEqual(len(view), 1)
-                self.assertIn("dist.integrity", view[0])
-                expected = agent_catalog()[agent_id]["package"]["integrity"]
-                self.assertTrue(expected.startswith("sha512-"))
-                # And the check happens before the install, not after.
-                self.assertLess(runner.calls.index(view[0]), runner.calls.index(runner.install_calls[0]))
-
-    def test_a_registry_serving_a_different_package_is_refused(self):
-        # The case a mirror has to be held to: npm would verify the download
-        # against whatever the registry declared, so only the manifest can say
-        # the declaration is the official release.
-        runner = RecordingRunner(integrity="sha512-tampered")
-        with self.assertRaises(OneAgentError) as caught:
-            self.install(runtime_with(runner=runner, present={"npm"}), registry="npmmirror")
-        self.assertEqual(caught.exception.code, "AGENT_INSTALL_FAILED")
-        self.assertIn("Checksum mismatch", str(caught.exception))
-        self.assertIn("sha512-tampered", str(caught.exception))
-        self.assertEqual(runner.install_calls, [])
-
-    def test_a_missing_version_on_a_mirror_is_not_silently_downgraded(self):
-        # The boundary requires reporting an unreachable source rather than
-        # falling back to some other version.
-        runner = RecordingRunner(integrity_returncode=1)
-        with self.assertRaises(OneAgentError) as caught:
-            self.install(runtime_with(runner=runner, present={"npm"}), registry="npmmirror")
-        self.assertEqual(caught.exception.code, "AGENT_INSTALL_FAILED")
-        self.assertIn("not available", str(caught.exception))
-        self.assertEqual(runner.install_calls, [])
-
-    def test_the_checksum_query_uses_the_same_registry_as_the_install(self):
-        # Checking the official registry and installing from a mirror would
-        # verify the wrong thing.
-        runner = RecordingRunner()
-        self.install(runtime_with(runner=runner, present={"npm"}), registry="npmmirror")
-        expected = PACKAGE_MIRRORS["npmmirror"]["registry"]
-        view = [call for call in runner.calls if "view" in call][0]
-        self.assertIn(f"--registry={expected}", view)
-
-    def test_latest_skips_the_checksum_because_the_manifest_cannot_describe_it(self):
-        runner = RecordingRunner()
-        self.install(runtime_with(runner=runner, present={"npm"}), latest=True)
-        self.assertEqual([call for call in runner.calls if "view" in call], [])
-
-    def test_an_unreachable_registry_fails_closed_rather_than_installing(self):
-        # A checksum that cannot be read is not a checksum that matched, so both
-        # a hung registry and a missing npm must stop the install.
-        def hangs(args, **kwargs):  # noqa: ANN001
-            raise subprocess.TimeoutExpired([str(item) for item in args], 1)
-
-        with self.assertRaises(OneAgentError) as timed_out:
-            self.install(runtime_with(runner=hangs, present={"npm"}))
-        self.assertEqual(timed_out.exception.code, "AGENT_INSTALL_FAILED")
-        self.assertIn("Timed out", str(timed_out.exception))
-        self.assertTrue(timed_out.exception.retryable)
-
-        def broken(args, **kwargs):  # noqa: ANN001
-            raise OSError("npm vanished")
-
-        with self.assertRaises(OneAgentError) as failed:
-            self.install(runtime_with(runner=broken, present={"npm"}))
-        self.assertEqual(failed.exception.code, "AGENT_INSTALL_FAILED")
-        self.assertIn("Cannot read the checksum", str(failed.exception))
-
-    def test_a_package_without_a_recorded_checksum_is_not_blocked(self):
-        # uv entries carry no npm integrity; the guard must be "verify when a
-        # value exists", not "refuse everything unverified".
-        runner = RecordingRunner()
-        runtime = runtime_with(runner=runner, present={"npm"})
-        meta = json.loads(json.dumps(agent_catalog()["codex"]))
-        meta["package"].pop("integrity")
-        install_locked_agent(
-            runtime, "codex", meta, enforce_locked=True, latest=False, timeout=180, registry=""
-        )
-        self.assertEqual([call for call in runner.calls if "view" in call], [])
-        self.assertEqual(len(runner.install_calls), 1)
-
-    def test_uv_packages_are_not_subject_to_the_npm_checksum_path(self):
-        runner = RecordingRunner()
-        self.install(runtime_with(runner=runner, present={"uv", "python3.12"}), "aider")
-        self.assertEqual([call for call in runner.calls if "dist.integrity" in call], [])
-
-
-class InstallManyRegistryTests(unittest.TestCase):
-    """The registry has to reach install_many and show up in its log."""
-
-    def run_install(self, *, registry: str, versions: dict[str, str] | None = None):
-        runner = RecordingRunner(versions=versions)
-        present = {"npm", "codex"} if versions else {"npm"}
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime(
-                home=Path(tmp),
-                os_id="linux",
-                runner=runner,
-                which=lambda name: f"/usr/bin/{name}" if name in present else None,
-                env={},
-            )
-            result = install_many(
-                InstallOptions(
-                    agents=["codex"],
-                    configure=False,
-                    install_agent=True,
-                    check_agent_only=True,
-                    locked_version=True,
-                    registry=registry,
-                    home=Path(tmp),
-                    os_id="linux",
-                ),
-                runtime,
-            )
-        return runner, result
-
-    def test_the_log_names_the_registry_a_package_came_from(self):
-        # Without this the user has no way to tell afterwards whether a package
-        # came from the official source or a mirror.
-        _, result = self.run_install(registry="npmmirror")
-        expected = PACKAGE_MIRRORS["npmmirror"]["registry"]
-        self.assertIn(f"registry: {expected}", result["log"])
-
-    def test_nothing_is_logged_when_no_installation_happened(self):
-        # Already at the locked version: install_locked_agent short-circuits and
-        # reports no registry, so the log must not claim one was used.
-        locked = agent_catalog()["codex"]["package"]["version"]
-        _, result = self.run_install(registry="npmmirror", versions={"codex": locked})
-        self.assertNotIn("registry:", result["log"])
-
-
-class PrerequisiteTests(unittest.TestCase):
-    def install(self, agent_id: str, runtime: Runtime):
-        return install_locked_agent(
-            runtime, agent_id, agent_catalog()[agent_id], enforce_locked=True, latest=False, timeout=180
-        )
-
-    def test_missing_npm_is_reported_before_anything_runs(self):
-        # Otherwise the failure surfaces as a FileNotFoundError from the runner,
-        # which tells the user nothing about what to install.
-        runner = RecordingRunner()
-        runtime = runtime_with(runner=runner, present=set())
-        for agent_id in ("codex", "claude-code"):
-            with self.subTest(agent=agent_id):
-                with self.assertRaises(OneAgentError) as caught:
-                    self.install(agent_id, runtime)
-                self.assertEqual(caught.exception.code, "PREREQUISITE_MISSING")
-                self.assertIn("npm", str(caught.exception))
-        self.assertEqual(runner.install_calls, [])
-
-    def test_claude_code_on_windows_requires_git(self):
-        # Declared as windows_prerequisites in the lock manifest; Claude Code
-        # shells out to Git Bash there.
-        runtime = runtime_with(runner=RecordingRunner(), present={"npm"}, os_id="windows")
-        with self.assertRaises(OneAgentError) as caught:
-            self.install("claude-code", runtime)
-        self.assertEqual(caught.exception.code, "PREREQUISITE_MISSING")
-        # The message is derived from the lock manifest: it names the declared
-        # prerequisite and the Agent, not a string written into the installer.
-        self.assertIn("git", str(caught.exception))
-        self.assertIn("Claude Code", str(caught.exception))
-
-        # With git present the same call proceeds.
-        with_git = RecordingRunner()
-        self.install("claude-code", runtime_with(runner=with_git, present={"npm", "git"}, os_id="windows"))
-        self.assertEqual(len(with_git.install_calls), 1)
-
-    def test_codex_on_windows_does_not_require_git(self):
-        runner = RecordingRunner()
-        self.install("codex", runtime_with(runner=runner, present={"npm"}, os_id="windows"))
-        self.assertEqual(len(runner.install_calls), 1)
-
-
-class InstallFailureTests(unittest.TestCase):
-    def install(self, runtime: Runtime, agent_id: str = "codex"):
-        return install_locked_agent(
-            runtime, agent_id, agent_catalog()[agent_id], enforce_locked=True, latest=False, timeout=180
-        )
-
-    def test_a_failing_installer_is_retryable_and_keeps_its_output(self):
-        runner = RecordingRunner(returncode=1)
-        with self.assertRaises(OneAgentError) as caught:
-            self.install(runtime_with(runner=runner, present={"npm"}))
-        self.assertEqual(caught.exception.code, "AGENT_INSTALL_FAILED")
-        self.assertTrue(caught.exception.retryable)
-        self.assertIn("boom", str(caught.exception))
-
-    def test_a_timeout_is_reported_as_a_timeout(self):
-        integrity = agent_catalog()["codex"]["package"]["integrity"]
-
-        def slow(args, **kwargs):  # noqa: ANN001
-            argv = [str(item) for item in args]
-            if "install" in argv:
-                raise subprocess.TimeoutExpired(argv, 1)
-            return subprocess.CompletedProcess(argv, 0, f"{integrity}\n", "")
-
-        runtime = runtime_with(runner=slow, present={"npm"})
-        with self.assertRaises(OneAgentError) as caught:
-            self.install(runtime)
-        self.assertEqual(caught.exception.code, "TIMEOUT")
-        self.assertTrue(caught.exception.retryable)
-
-    def test_installer_output_cannot_leak_a_credential_from_the_environment(self):
-        # The failure detail quotes the installer's stderr, and npm echoes the
-        # environment it ran with on some errors.
-        secret = "sk-contract-should-not-appear"
-
-        integrity = agent_catalog()["codex"]["package"]["integrity"]
-
-        def leaky(args, **kwargs):  # noqa: ANN001
-            argv = [str(item) for item in args]
-            if "install" not in argv:
-                return subprocess.CompletedProcess(argv, 0, f"{integrity}\n", "")
-            return subprocess.CompletedProcess(argv, 1, "", f"failed with ANTHROPIC_API_KEY={secret}")
-
-        runtime = runtime_with(
-            runner=leaky, present={"npm"}, env={"ANTHROPIC_API_KEY": secret, "PATH": "/usr/bin"}
-        )
-        with self.assertRaises(OneAgentError) as caught:
-            self.install(runtime)
-        self.assertNotIn(secret, str(caught.exception))
-        self.assertIn("[redacted]", str(caught.exception))
-
-
-if __name__ == "__main__":
-    unittest.main()
diff --git a/tests/test_rc_scripts.py b/tests/test_rc_scripts.py
deleted file mode 100644
index ddcbb35c..00000000
--- a/tests/test_rc_scripts.py
+++ /dev/null
@@ -1,354 +0,0 @@
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-import sys
-import tempfile
-import threading
-import unittest
-from http.server import BaseHTTPRequestHandler, HTTPServer
-from pathlib import Path
-from unittest.mock import patch
-
-from oneagent.installer import Runtime
-from scripts.agent_config_adopted_check import classify_adoption, parse_env_file
-from scripts.provider_rc_smoke import (
-    ProviderSmokeConfig,
-    config_from_env,
-    load_api_key_json,
-    main as provider_smoke_main,
-    smoke_provider,
-)
-from scripts.verify_locked_agents import create_isolated_runtime, verify_locked_agents
-from tests.support import LocalHTTPServer
-
-
-ROOT = Path(__file__).resolve().parents[1]
-
-
-class ProtocolHandler(BaseHTTPRequestHandler):
-    requests: list[dict[str, object]] = []
-
-    def log_message(self, *_args):
-        return
-
-    def _record(self, body: bytes = b""):
-        self.requests.append(
-            {
-                "path": self.path,
-                "authorization": self.headers.get("Authorization"),
-                "x_api_key": self.headers.get("X-Api-Key"),
-                "body": json.loads(body.decode()) if body else None,
-            }
-        )
-        self.send_response(200)
-        self.send_header("Content-Type", "application/json")
-        self.end_headers()
-        self.wfile.write(b'{"ok":true}')
-
-    def do_GET(self):
-        self._record()
-
-    def do_POST(self):
-        length = int(self.headers.get("Content-Length", "0"))
-        self._record(self.rfile.read(length))
-
-
-class ReleaseCandidateScriptTests(unittest.TestCase):
-    def test_provider_smoke_script_can_run_directly(self):
-        result = subprocess.run(
-            [sys.executable, str(ROOT / "scripts" / "provider_rc_smoke.py"), "--help"],
-            cwd=ROOT,
-            capture_output=True,
-            text=True,
-            check=False,
-        )
-        self.assertEqual(result.returncode, 0, result.stderr)
-        self.assertIn("--provider", result.stdout)
-
-    def test_provider_smoke_covers_all_protocols_without_key_in_urls(self):
-        ProtocolHandler.requests = []
-        server = LocalHTTPServer(("127.0.0.1", 0), ProtocolHandler)
-        thread = threading.Thread(target=server.serve_forever, daemon=True)
-        thread.start()
-        try:
-            base = f"http://127.0.0.1:{server.server_port}"
-            results = smoke_provider(
-                ProviderSmokeConfig(
-                    provider="ppio",
-                    api_key="sentinel-rc-key",
-                    openai_model="chat-model",
-                    anthropic_model="anthropic-model",
-                    responses_model="responses-model",
-                    openai_base=base,
-                    anthropic_base=base + "/anthropic",
-                ),
-                timeout=2,
-            )
-        finally:
-            server.shutdown()
-            server.server_close()
-            thread.join(timeout=5)
-        self.assertEqual(set(results), {"models", "chat", "responses", "anthropic"})
-        self.assertEqual(
-            [item["path"] for item in ProtocolHandler.requests],
-            ["/v1/models", "/v1/chat/completions", "/v1/responses", "/anthropic/v1/messages"],
-        )
-        self.assertTrue(all("sentinel-rc-key" not in str(item["path"]) for item in ProtocolHandler.requests))
-        self.assertEqual(ProtocolHandler.requests[-1]["x_api_key"], "sentinel-rc-key")
-
-    def test_apiproxy_profile_keeps_three_protocol_model_slots(self):
-        with patch.dict(os.environ, {}, clear=True):
-            config = config_from_env("apiproxy")
-        self.assertEqual(config.openai_base, "https://apiproxy.paigod.work")
-        self.assertEqual(config.anthropic_base, "https://apiproxy.paigod.work")
-        self.assertEqual(config.openai_model, "openai/gpt-5.6-terra")
-        self.assertEqual(config.anthropic_model, "openai/gpt-5.6-terra")
-        self.assertEqual(config.responses_model, "openai/gpt-5.6-terra")
-
-    def test_formal_provider_does_not_inherit_temporary_proxy_defaults(self):
-        with patch.dict(os.environ, {}, clear=True):
-            config = config_from_env("ppio")
-        self.assertEqual(config.openai_model, "")
-        self.assertEqual(config.anthropic_model, "")
-        self.assertEqual(config.responses_model, "")
-        self.assertEqual(config.openai_base, "")
-        self.assertEqual(config.anthropic_base, "")
-
-    def test_local_json_key_is_loaded_without_appearing_in_cli_output(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            auth_file = Path(tmp) / "auth.json"
-            auth_file.write_text(json.dumps({"OPENAI_API_KEY": "sentinel-json-key"}), encoding="utf-8")
-            self.assertEqual(load_api_key_json(auth_file, "OPENAI_API_KEY"), "sentinel-json-key")
-            with patch.object(
-                sys,
-                "argv",
-                [
-                    "provider_rc_smoke.py",
-                    "--provider",
-                    "apiproxy",
-                    "--api-key-json",
-                    str(auth_file),
-                ],
-            ), patch(
-                "scripts.provider_rc_smoke.smoke_provider",
-                return_value={"models": 200, "chat": 200, "responses": 200, "anthropic": 200},
-            ) as smoke, patch("builtins.print") as output:
-                provider_smoke_main()
-        config = smoke.call_args.args[0]
-        self.assertEqual(config.api_key, "sentinel-json-key")
-        self.assertNotIn("sentinel-json-key", " ".join(str(call) for call in output.call_args_list))
-
-    def test_formal_all_mode_excludes_local_apiproxy_profile(self):
-        with patch.object(
-            sys,
-            "argv",
-            ["provider_rc_smoke.py", "--provider", "all"],
-        ), patch(
-            "scripts.provider_rc_smoke.smoke_provider",
-            return_value={"models": 200, "chat": 200, "responses": 200, "anthropic": 200},
-        ) as smoke, patch("builtins.print"):
-            provider_smoke_main()
-        self.assertEqual([call.args[0].provider for call in smoke.call_args_list], ["ppio", "novita"])
-
-    def test_locked_agent_verifier_rejects_version_mismatch(self):
-        manifest = {
-            "agents": {
-                "agent": {
-                    "name": "Agent",
-                    "config_mode": "auto",
-                    "command": "agent",
-                    "version_args": ["--version"],
-                    "package": {"version": "1.2.3"},
-                }
-            }
-        }
-        with tempfile.TemporaryDirectory() as tmp:
-            runtime = Runtime.create(home=Path(tmp), os_id="linux", which=lambda _name: "/bin/agent")
-            runtime.runner = lambda args, **_kwargs: subprocess.CompletedProcess(args, 0, "agent 9.9.9", "")
-            with patch("scripts.verify_locked_agents.load_manifest", return_value=manifest), patch(
-                "scripts.verify_locked_agents.install_many",
-                return_value={"ok": True, "results": [{"status": "installed"}]},
-            ):
-                with self.assertRaisesRegex(RuntimeError, "expected 1.2.3"):
-                    verify_locked_agents(runtime)
-
-    def test_locked_agent_verifier_isolates_home_package_managers_and_secrets(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-            toolchain = root / "toolchain"
-            toolchain.mkdir()
-            npm = toolchain / ("npm.cmd" if os.name == "nt" else "npm")
-            npm.write_text("", encoding="utf-8")
-            npm.chmod(0o755)
-            system_codex = toolchain / ("codex.cmd" if os.name == "nt" else "codex")
-            system_codex.write_text("", encoding="utf-8")
-            system_codex.chmod(0o755)
-            runtime = create_isolated_runtime(
-                root / "cleanroom",
-                os_id="windows" if os.name == "nt" else "linux",
-                base_env={
-                    "PATH": str(toolchain),
-                    "OPENAI_API_KEY": "sentinel-rc-secret",
-                    "UV_CONFIG_FILE": str(root / "real-uv.toml"),
-                    "SAFE_VALUE": "preserved",
-                },
-            )
-            self.assertIsNone(runtime.which("codex"))
-            if os.name != "nt":
-                aider_target = Path(runtime.env["UV_TOOL_DIR"]) / "aider-chat" / "bin" / "aider"
-                aider_target.parent.mkdir(parents=True)
-                aider_target.write_text("#!/bin/sh\n", encoding="utf-8")
-                aider_target.chmod(0o755)
-                aider_link = Path(runtime.env["UV_TOOL_BIN_DIR"]) / "aider"
-                aider_link.symlink_to(aider_target)
-                self.assertEqual(Path(runtime.which("aider") or ""), aider_link)
-        self.assertEqual(runtime.env["HOME"], str(root / "cleanroom" / "home"))
-        self.assertEqual(runtime.env["ONEAGENT_HOME"], runtime.env["HOME"])
-        self.assertTrue(runtime.env["NPM_CONFIG_PREFIX"].startswith(str(root / "cleanroom")))
-        self.assertTrue(runtime.env["UV_TOOL_DIR"].startswith(str(root / "cleanroom")))
-        self.assertTrue(runtime.env["UV_TOOL_BIN_DIR"].startswith(str(root / "cleanroom")))
-        self.assertTrue(runtime.env["NPM_CONFIG_USERCONFIG"].startswith(str(root / "cleanroom")))
-        self.assertTrue(runtime.env["XDG_CONFIG_HOME"].startswith(str(root / "cleanroom")))
-        self.assertNotIn("UV_CONFIG_FILE", runtime.env)
-        self.assertNotIn("OPENAI_API_KEY", runtime.env)
-        self.assertEqual(runtime.env["SAFE_VALUE"], "preserved")
-
-
-class VerificationScriptTests(unittest.TestCase):
-    """The two scripts that verify a blank machine can run these Agents."""
-
-    def test_agent_e2e_smoke_refuses_to_run_without_a_real_credential(self):
-        # It exists to prove an Agent answers a real request; silently proceeding
-        # keyless would report a pass that means nothing.
-        environment = {key: value for key, value in os.environ.items() if key != "ONEAGENT_API_KEY"}
-        result = subprocess.run(
-            [sys.executable, str(ROOT / "scripts" / "agent_e2e_smoke.py")],
-            capture_output=True,
-            text=True,
-            timeout=120,
-            env=environment,
-        )
-        self.assertNotEqual(result.returncode, 0)
-        self.assertIn("ONEAGENT_API_KEY", result.stdout + result.stderr)
-
-    def test_agent_e2e_smoke_exercises_both_protocols_and_redacts(self):
-        source = (ROOT / "scripts" / "agent_e2e_smoke.py").read_text(encoding="utf-8")
-        # Codex speaks Responses and Claude Code speaks Anthropic Messages, so
-        # neither can stand in for the other.
-        self.assertIn('AGENTS = ("codex", "claude-code")', source)
-        # The probe has to run; --skip-test here would leave the endpoint pairing
-        # unverified, which is the thing this layer is for.
-        self.assertIn("skip_test=False", source)
-        # Both Agents default to a REPL; a smoke has to use the one-shot form.
-        self.assertIn('"exec"', source)
-        self.assertIn('"-p"', source)
-        self.assertIn("redact(", source)
-
-    def test_real_install_cleanroom_isolates_the_prefix_and_watches_real_home(self):
-        source = (ROOT / "tests" / "real_install_test.sh").read_text(encoding="utf-8")
-        # A developer's globally installed Agent must not be able to satisfy the
-        # assertions, so the throwaway prefix comes first on PATH.
-        self.assertIn('npm_config_prefix="$NPM_PREFIX"', source)
-        self.assertIn('CLEAN_PATH="$NPM_PREFIX/bin', source)
-        self.assertIn("env -i", source)
-        # The run must fail if it touched the real user's configuration.
-        self.assertIn("snapshot_real_home", source)
-        self.assertIn("real-home-before.json", source)
-        # It only covers the two Agents under verification.
-        self.assertIn("--agent codex,claude-code", source)
-        self.assertIn("--locked-version", source)
-        # And it must actually install, unlike the suites that stub the runner.
-        self.assertIn("--install-agent", source)
-        self.assertIn("ONEAGENT_REGISTRY", source)
-
-    def test_real_install_cleanroom_checks_path_version_and_secrecy(self):
-        source = (ROOT / "tests" / "real_install_test.sh").read_text(encoding="utf-8")
-        # The step no other suite covers: npm putting the binary where PATH can
-        # find it.
-        self.assertIn("command -v", source)
-        self.assertIn("did not land anywhere on PATH", source)
-        self.assertIn("--version", source)
-        self.assertIn("profile.json", source)
-        self.assertIn("MOCK_KEY", source)
-
-
-class ConfigAdoptionCheckTests(unittest.TestCase):
-    """The keyless check that a configured Agent adopts what OneAgent wrote.
-
-    The classifier is the discriminator between this round's two outcomes --
-    Codex adopted (connection failure) and Claude Code not adopted ("Not logged
-    in") -- so it is unit-tested here, in ordinary CI, against the real outputs.
-    Running the Agents themselves needs them installed and happens in the
-    release-candidate workflow.
-    """
-
-    def test_connection_failure_is_read_as_adopted(self):
-        # Codex echoes the provider section it read, then fails to reach the
-        # discard port.
-        adopted, reason = classify_adoption("provider: oneagent\nERROR: Reconnecting... 1/5")
-        self.assertTrue(adopted, reason)
-        # Claude Code after the credential fix: it reaches for the endpoint and
-        # the socket is refused.
-        adopted, reason = classify_adoption("API Error: fetch failed (connect ECONNREFUSED 127.0.0.1:9)")
-        self.assertTrue(adopted, reason)
-
-    def test_auth_error_is_read_as_not_adopted(self):
-        # The exact defect: reported configured, but answering about login rather
-        # than the network means the configuration never reached the Agent.
-        adopted, reason = classify_adoption("Not logged in · Please run /login")
-        self.assertFalse(adopted, reason)
-        self.assertIn("not adopted", reason)
-
-    def test_auth_signal_wins_when_both_layers_appear(self):
-        # A verbose error mentioning both is the failure, never a pass.
-        adopted, _ = classify_adoption("connection failed; also Not logged in")
-        self.assertFalse(adopted)
-
-    def test_unknown_output_is_not_confirmed(self):
-        adopted, reason = classify_adoption("everything is fine")
-        self.assertFalse(adopted)
-        self.assertIn("neither", reason)
-
-    def test_parse_env_file_reads_bash_and_powershell_forms(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            bash = Path(tmp) / "agent.env"
-            bash.write_text(
-                "export ANTHROPIC_AUTH_TOKEN='secret value'\nexport ANTHROPIC_MODEL=m\n",
-                encoding="utf-8",
-            )
-            self.assertEqual(
-                parse_env_file(bash),
-                {"ANTHROPIC_AUTH_TOKEN": "secret value", "ANTHROPIC_MODEL": "m"},
-            )
-            powershell = Path(tmp) / "agent.env.ps1"
-            powershell.write_text("$env:ONEAGENT_API_KEY_CODEX = 'k'\n", encoding="utf-8")
-            self.assertEqual(parse_env_file(powershell), {"ONEAGENT_API_KEY_CODEX": "k"})
-
-    def test_script_needs_no_key_and_targets_the_discard_port(self):
-        source = (ROOT / "scripts" / "agent_config_adopted_check.py").read_text(encoding="utf-8")
-        # The real-key threshold is what hid the defect; this layer must not
-        # reintroduce it.
-        self.assertNotIn("ONEAGENT_API_KEY", source)
-        self.assertIn('DISCARD_BASE_URL = "http://127.0.0.1:9"', source)
-        # The discard port cannot answer a probe; probing would only block the
-        # config write this check is for.
-        self.assertIn("skip_test=True", source)
-        result = subprocess.run(
-            [sys.executable, str(ROOT / "scripts" / "agent_config_adopted_check.py"), "--help"],
-            cwd=ROOT,
-            capture_output=True,
-            text=True,
-            timeout=120,
-        )
-        self.assertEqual(result.returncode, 0, result.stderr)
-        self.assertIn("--agents", result.stdout)
-
-    def test_release_candidate_runs_the_keyless_adoption_check(self):
-        rc = (ROOT / ".github" / "workflows" / "release-candidate.yml").read_text(encoding="utf-8")
-        self.assertIn("scripts/agent_config_adopted_check.py", rc)
-
-
-if __name__ == "__main__":
-    unittest.main()
diff --git a/tests/test_release_policy.py b/tests/test_release_policy.py
deleted file mode 100644
index fe4bdfa7..00000000
--- a/tests/test_release_policy.py
+++ /dev/null
@@ -1,548 +0,0 @@
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import re
-import shutil
-import subprocess
-import tempfile
-import unittest
-import zipfile
-from pathlib import Path
-from unittest.mock import patch
-
-from oneagent import catalog, entrypoint
-from oneagent.catalog import load_manifest
-from oneagent.installer import Runtime, status_payload
-from scripts import build_release
-from scripts.check_release import inspect_zip, validate_manifest
-from scripts.stage_resources import prune_stale_build_output, stage_resources
-
-
-ROOT = Path(__file__).resolve().parents[1]
-
-
-class ReleasePolicyTests(unittest.TestCase):
-    def test_every_auto_agent_declares_what_the_installer_relies_on(self):
-        # The installer derives the start command, the restart hint and the
-        # credential route from these fields instead of restating them per Agent,
-        # so a missing one is a broken Agent rather than a missing default. The
-        # credential route in particular: Claude Code shipped reported as
-        # configured while starting unauthenticated, because nothing declared
-        # that it only reads its own variable names.
-        manifest = load_manifest()
-        for agent_id, meta in manifest["agents"].items():
-            if meta.get("config_mode") != "auto":
-                continue
-            with self.subTest(agent=agent_id):
-                self.assertTrue(meta.get("command"), f"{agent_id} has no command")
-                self.assertTrue(meta.get("config_path"), f"{agent_id} has no config_path")
-                self.assertTrue(meta.get("config_adapter"), f"{agent_id} has no config_adapter")
-                delivery = meta.get("credential_delivery")
-                self.assertIn(delivery, {"oneagent_env", "native_env", "config_file"})
-                if delivery == "native_env":
-                    # Otherwise the declaration promises native variables and the
-                    # env file would define none of them.
-                    declared = meta.get("env_vars") or {}
-                    self.assertTrue(declared.get("api_key"), f"{agent_id} names no credential variable")
-                    for field, name in declared.items():
-                        self.assertRegex(str(name), r"^[A-Z][A-Z0-9_]*$", f"{agent_id}.{field}")
-
-    def test_lock_manifest_never_uses_latest_or_unapproved_manager(self):
-        manifest = load_manifest()
-        for agent_id, meta in manifest["agents"].items():
-            package = meta.get("package")
-            if not package:
-                continue
-            with self.subTest(agent=agent_id):
-                self.assertNotEqual(package["version"], "latest")
-                self.assertIn(package["manager"], {"npm", "uv"})
-                if package["manager"] == "npm":
-                    self.assertRegex(package.get("integrity", ""), r"^sha512-")
-                if agent_id == "aider":
-                    self.assertEqual(package["manager"], "uv")
-                self.assertTrue(package["source"].startswith("https://"))
-                self.assertTrue(package["license_url"].startswith("https://"))
-
-    def test_runtime_code_does_not_use_shell_true_or_curl_pipe(self):
-        # Scans oneagent/ and scripts/ to match the Docker cleanroom's
-        # policy-scan exactly. When this test covered only oneagent/, a
-        # violation under scripts/ passed every local check and surfaced only
-        # after a full container run in CI.
-        for directory in ("oneagent", "scripts"):
-            sources = "\n".join(
-                path.read_text(encoding="utf-8") for path in sorted((ROOT / directory).glob("*.py"))
-            )
-            with self.subTest(directory=directory):
-                # The cleanroom greps raw text, so a comment containing the
-                # literal token trips it too. Describe the rule without
-                # spelling it out rather than softening the scan.
-                self.assertNotRegex(sources, r"shell\s*=\s*True")
-                self.assertNotRegex(sources, r"curl\s+[^\n|]+\|\s*(?:ba)?sh")
-
-    def test_no_bare_http_server_reintroduces_the_reverse_dns_stall(self):
-        # http.server's server_bind() calls socket.getfqdn(). On a host with no
-        # reverse resolver that blocks ~35s per process, which is why the macOS
-        # CI jobs used to spend 44s on a 9s test step. Every server must come
-        # from a subclass that overrides the bind.
-        offenders: list[str] = []
-        for directory in ("oneagent", "scripts", "tests"):
-            for path in sorted((ROOT / directory).glob("*.py")):
-                text = path.read_text(encoding="utf-8")
-                for line_number, line in enumerate(text.splitlines(), start=1):
-                    if re.search(r"(?<![A-Za-z0-9_])HTTPServer\(\(", line):
-                        offenders.append(f"{directory}/{path.name}:{line_number}")
-        self.assertEqual(
-            offenders,
-            [],
-            "use LocalHTTPServer (tests) or OneAgentHTTPServer (product) instead of a bare HTTPServer",
-        )
-
-    def test_external_tools_are_resolved_to_an_absolute_path(self):
-        # Windows ships npm as npm.cmd and CreateProcess only appends .exe to a
-        # bare name, so subprocess.run(["npm", ...]) raises FileNotFoundError
-        # there. shutil.which honours PATHEXT; shell=True is not an option.
-        with patch.object(build_release.shutil, "which", return_value=r"C:\Program Files\nodejs\npm.cmd"):
-            self.assertEqual(
-                build_release.resolve_tool("npm", "install Node.js"),
-                r"C:\Program Files\nodejs\npm.cmd",
-            )
-        with patch.object(build_release.shutil, "which", return_value=None):
-            with self.assertRaises(SystemExit) as missing:
-                build_release.resolve_tool("npm", "install Node.js")
-        self.assertIn("install Node.js", str(missing.exception))
-
-        source = (ROOT / "scripts" / "build_release.py").read_text(encoding="utf-8")
-        self.assertNotIn('run(["npm"', source)
-        self.assertIn('resolve_tool("npm"', source)
-
-    def test_release_scripts_default_to_unsigned_preview(self):
-        source = (ROOT / "scripts" / "build_release.py").read_text(encoding="utf-8")
-        self.assertIn('default="technical-preview-unsigned"', source)
-        self.assertIn("Stable macOS builds require signing", source)
-        self.assertIn("Stable Windows builds require Authenticode", source)
-
-    def test_stable_signature_gate_inspects_the_artifact_not_an_env_var(self):
-        # Setting ONEAGENT_MACOS_SIGNED=1 used to be enough to publish an
-        # unsigned build as Stable. The gate must interrogate the binary.
-        calls: list[list[str]] = []
-
-        def refuse(args, **_kwargs):
-            calls.append([str(item) for item in args])
-            return subprocess.CompletedProcess(args, 1, "", "code object is not signed at all")
-
-        with tempfile.TemporaryDirectory() as tmp:
-            bundle = Path(tmp) / "OneAgent"
-            bundle.mkdir()
-            with patch.dict(os.environ, {"ONEAGENT_MACOS_SIGNED": "1", "ONEAGENT_WINDOWS_SIGNED": "1"}):
-                # The pre-flight check is satisfied by the env var alone...
-                build_release.ensure_unsigned_channel("stable", "macos")
-                # ...but the artifact check still refuses an unsigned bundle.
-                with patch.object(build_release.subprocess, "run", side_effect=refuse):
-                    with self.assertRaises(SystemExit) as macos:
-                        build_release.verify_stable_signature("stable", "macos", bundle)
-                    self.assertIn("Developer ID signature", str(macos.exception))
-                    self.assertEqual(calls[0][0], "codesign")
-
-                    calls.clear()
-                    with self.assertRaises(SystemExit) as windows:
-                        build_release.verify_stable_signature("stable", "windows", bundle)
-                    self.assertIn("Authenticode", str(windows.exception))
-                    self.assertEqual(calls[0][0], "powershell")
-
-            # A missing toolchain must fail closed rather than skip the check.
-            with patch.object(build_release.subprocess, "run", side_effect=OSError("codesign missing")):
-                with self.assertRaises(SystemExit):
-                    build_release.verify_stable_signature("stable", "macos", bundle)
-
-            # The unsigned preview channel never invokes the signing tools.
-            with patch.object(build_release.subprocess, "run", side_effect=AssertionError("must not run")):
-                build_release.verify_stable_signature("technical-preview-unsigned", "macos", bundle)
-                build_release.verify_stable_signature("technical-preview-unsigned", "windows", bundle)
-
-    def test_wheel_build_stages_the_runtime_resources(self):
-        # A wheel only carries files inside the package directory. Without this
-        # staging step an installed OneAgent starts and immediately fails with
-        # "Cannot load Agent lock manifest". Staged into a throwaway tree so the
-        # real working copy is untouched.
-        with tempfile.TemporaryDirectory() as tmp:
-            fake = Path(tmp).resolve()
-            (fake / "oneagent").mkdir()
-            (fake / "frontend" / "dist" / "assets").mkdir(parents=True)
-            shutil.copy2(ROOT / "agents.lock.json", fake / "agents.lock.json")
-            (fake / "frontend" / "dist" / "index.html").write_text("<!doctype html>", encoding="utf-8")
-            (fake / "frontend" / "dist" / "assets" / "app.js").write_text("//", encoding="utf-8")
-
-            staged = stage_resources(fake)
-            self.assertEqual(
-                json.loads((staged / "agents.lock.json").read_text(encoding="utf-8")),
-                json.loads((ROOT / "agents.lock.json").read_text(encoding="utf-8")),
-            )
-            self.assertTrue((staged / "frontend" / "dist" / "index.html").is_file())
-            self.assertTrue((staged / "frontend" / "dist" / "assets" / "app.js").is_file())
-
-            # Re-staging must not accumulate files removed from the source.
-            (fake / "frontend" / "dist" / "assets" / "app.js").unlink()
-            staged = stage_resources(fake)
-            self.assertFalse((staged / "frontend" / "dist" / "assets" / "app.js").exists())
-
-        # The build must actually invoke the staging, and the declared package
-        # data must cover what it produces.
-        setup_source = (ROOT / "setup.py").read_text(encoding="utf-8")
-        self.assertIn("stage_resources", setup_source)
-        self.assertIn("build_py", setup_source)
-        pyproject = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
-        self.assertIn("_resources/agents.lock.json", pyproject)
-        self.assertIn("_resources/frontend/dist", pyproject)
-
-    def test_stale_build_output_cannot_ship_an_outdated_manifest(self):
-        # setuptools copies package data into build/lib and never prunes it,
-        # and build/ survives between builds. A wheel was therefore packaging
-        # whatever _resources happened to be there -- verified by breaking the
-        # staging step and still getting a complete wheel. For a project whose
-        # premise is version locking, shipping a stale agents.lock.json is the
-        # worst version of that bug.
-        with tempfile.TemporaryDirectory() as tmp:
-            build_lib = Path(tmp).resolve() / "lib"
-            stale = build_lib / "oneagent" / "_resources"
-            (stale / "frontend" / "dist").mkdir(parents=True)
-            (stale / "agents.lock.json").write_text('{"stale": true}', encoding="utf-8")
-
-            self.assertEqual(prune_stale_build_output(build_lib), stale)
-            self.assertFalse(stale.exists())
-            # Sibling modules in build/lib must survive; only the staged tree goes.
-            self.assertTrue((build_lib / "oneagent").is_dir())
-
-            # Nothing staged yet is not an error.
-            self.assertIsNone(prune_stale_build_output(build_lib))
-
-        setup_source = (ROOT / "setup.py").read_text(encoding="utf-8")
-        self.assertIn("prune_stale_build_output(self.build_lib)", setup_source)
-
-    def test_source_checkout_wins_over_a_stale_staging_directory(self):
-        # Building a wheel locally leaves oneagent/_resources/ in the working
-        # tree; it must never shadow the repository's real manifest.
-        with tempfile.TemporaryDirectory() as tmp:
-            # resource_root() resolves symlinks, and macOS hands out /var paths
-            # that are really /private/var.
-            root = Path(tmp).resolve()
-            package = root / "oneagent"
-            package.mkdir()
-            (root / "agents.lock.json").write_text("{}", encoding="utf-8")
-            stale = package / "_resources"
-            stale.mkdir()
-            (stale / "agents.lock.json").write_text("{}", encoding="utf-8")
-
-            with patch.object(catalog, "__file__", str(package / "catalog.py")):
-                self.assertEqual(catalog.resource_root(), root)
-                # With no manifest beside the package this is an installed
-                # distribution, so the staged copy is the only source.
-                (root / "agents.lock.json").unlink()
-                self.assertEqual(catalog.resource_root(), stale)
-
-    def test_source_launchers_require_python_312(self):
-        for relative in ["scripts/install.sh", "scripts/install.ps1", "scripts/gui.py"]:
-            with self.subTest(path=relative):
-                self.assertIn("3.12", (ROOT / relative).read_text(encoding="utf-8"))
-
-    def test_frontend_build_has_no_remote_assets_or_source_maps(self):
-        dist = ROOT / "frontend" / "dist"
-        if not dist.exists():
-            self.skipTest("frontend production build is not present")
-        self.assertFalse(list(dist.rglob("*.map")))
-        text = "\n".join(
-            path.read_text(encoding="utf-8", errors="ignore")
-            for path in dist.rglob("*")
-            if path.is_file() and path.suffix in {".html", ".js", ".css"}
-        )
-        self.assertNotRegex(text, r"https?://(?:fonts\.|cdn\.|unpkg\.|jsdelivr\.)")
-
-    def test_packaged_entrypoint_routes_no_args_to_gui_and_args_to_cli(self):
-        with patch.object(entrypoint.server, "main") as gui, patch.object(entrypoint.cli, "main") as cli:
-            with patch("sys.argv", ["OneAgent"]):
-                entrypoint.main()
-            gui.assert_called_once_with()
-            cli.assert_not_called()
-
-        with patch.object(entrypoint.server, "main") as gui, patch.object(entrypoint.cli, "main") as cli:
-            with patch("sys.argv", ["OneAgent", "--json"]):
-                entrypoint.main()
-            cli.assert_called_once_with()
-            gui.assert_not_called()
-
-    def test_source_archive_allowlist_excludes_runtime_and_concept_assets(self):
-        source = (ROOT / "scripts" / "build_release.py").read_text(encoding="utf-8")
-        allowlist = source.split("def source_files", 1)[1].split("def build_source_zip", 1)[0]
-        self.assertNotIn('"node_modules"', allowlist)
-        self.assertNotIn('"output"', allowlist)
-        self.assertIn('"Dockerfile.test"', allowlist)
-        self.assertIn('".dockerignore"', allowlist)
-
-    def test_source_archive_carries_no_generated_or_installed_files(self):
-        # The allowlist names whole directories and walks them, so adding a root
-        # silently picks up whatever a build left inside it. site/src/generated
-        # holds the public release index, whose checksums describe one machine's
-        # artifacts -- exactly what ADR-006 keeps out of the tree. Asserting on
-        # the resolved file list rather than the source text is what catches it.
-        selected = build_release.source_files()
-        self.assertTrue(selected, "source archive must not be empty")
-        offenders = [
-            str(path.relative_to(ROOT))
-            for path in selected
-            if {"generated", "node_modules", "__pycache__"} & set(path.parts)
-            # public/downloads holds copied release artifacts; the page that
-            # renders them is ordinary source and shares only the word.
-            or path.is_relative_to(ROOT / "site" / "public" / "downloads")
-        ]
-        self.assertEqual(offenders, [])
-        # Nothing in a source archive should be release-sized; a stray artifact
-        # or bundled dependency tree shows up here first.
-        oversized = [
-            f"{path.relative_to(ROOT)} ({path.stat().st_size // 1024} KiB)"
-            for path in selected
-            if path.stat().st_size > 1_000_000
-        ]
-        self.assertEqual(oversized, [])
-
-    def test_docker_cleanroom_contract_is_isolated_and_linux_only(self):
-        dockerfile = (ROOT / "Dockerfile.test").read_text(encoding="utf-8")
-        wrapper = (ROOT / "scripts" / "test_docker_cleanroom.sh").read_text(encoding="utf-8")
-        runner = (ROOT / "scripts" / "run_container_cleanroom.sh").read_text(encoding="utf-8")
-        dockerignore = (ROOT / ".dockerignore").read_text(encoding="utf-8")
-
-        self.assertIn(
-            "mcr.microsoft.com/playwright:v1.61.1-noble@sha256:5b8f294aff9041b7191c34a4bab3ac270157a28774d4b0660e9743297b697e48",
-            dockerfile,
-        )
-        self.assertIn("USER pwuser", dockerfile)
-        self.assertIn("Acquire::Retries=3", dockerfile)
-        self.assertIn("--network none", wrapper)
-        self.assertIn("--shm-size=1g", wrapper)
-        self.assertNotIn("/var/run/docker.sock", wrapper)
-        self.assertNotRegex(wrapper, r"(?:source|src)=\$?\{?HOME")
-        self.assertIn('expected_platform="linux"', runner)
-        self.assertIn('id -u', runner)
-        self.assertIn("ONEAGENT_DISABLE_BROWSER", runner)
-        self.assertIn("PASSWORD", runner)
-        self.assertIn("npm run e2e", runner)
-        self.assertIn("coverage-summary.json", runner)
-        for required in [".git", ".env*", "frontend/node_modules", "release", "output"]:
-            with self.subTest(pattern=required):
-                self.assertIn(required, dockerignore)
-
-    def test_macos_cleanroom_requires_real_darwin_and_native_binary(self):
-        source = (ROOT / "tests" / "macos_cleanroom_test.sh").read_text(encoding="utf-8")
-        self.assertIn('uname -s', source)
-        self.assertIn('Darwin', source)
-        self.assertIn('env -i', source)
-        self.assertIn('stat -f', source)
-        self.assertIn('ONEAGENT_PACKAGED_BINARY', source)
-        self.assertIn('Unexpected preinstalled Agent', source)
-        self.assertNotIn('ONEAGENT_TEST_OS', source)
-
-    def test_ci_runs_container_and_real_macos_cleanrooms(self):
-        ci = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
-        rc = (ROOT / ".github" / "workflows" / "release-candidate.yml").read_text(encoding="utf-8")
-        self.assertIn("container-cleanroom:", ci)
-        self.assertIn("scripts/test_docker_cleanroom.sh", ci)
-        self.assertIn("pyinstaller==6.21.0", ci)
-        self.assertIn("tests/macos_cleanroom_test.sh", ci)
-        self.assertIn("ONEAGENT_PACKAGED_BINARY", ci)
-        self.assertIn("tests/macos_cleanroom_test.sh", rc)
-
-    def test_install_path_is_verified_offline_in_ci_and_for_real_before_release(self):
-        # The command that installs an Agent was only ever exercised through a
-        # replaced runner that ignored its argv, so the contract suite has to run
-        # everywhere, and the real install has to run before a release.
-        ci = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
-        rc = (ROOT / ".github" / "workflows" / "release-candidate.yml").read_text(encoding="utf-8")
-        self.assertIn("tests.test_install_contract", ci)
-        self.assertIn("tests.test_install_contract", rc)
-        # Real installation stays out of ordinary CI: it would hit the registry
-        # on every commit.
-        self.assertNotIn("real_install_test.sh", ci)
-        self.assertIn("tests/real_install_test.sh", rc)
-        self.assertIn("scripts/verify_locked_agents.py", rc)
-
-    def test_existing_configuration_is_exercised_in_both_cleanrooms(self):
-        # Every cleanroom stage starts from an empty HOME, so a machine that
-        # already has Agent configuration -- the normal case for a tool meant to
-        # manage them over time -- had no coverage anywhere. That is the state
-        # status_payload used to report as configured with a null provider.
-        container = (ROOT / "scripts" / "run_container_cleanroom.sh").read_text(encoding="utf-8")
-        macos = (ROOT / "tests" / "macos_cleanroom_test.sh").read_text(encoding="utf-8")
-        ci = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
-        self.assertIn("tests/existing_config_test.sh", container)
-        self.assertIn("tests/existing_config_test.sh", macos)
-        self.assertIn("tests.test_config_discovery", ci)
-
-    def test_config_readers_never_extract_a_credential(self):
-        # Three of the five formats hold the key in plain text next to the
-        # endpoint, so a reader that reached for one field too many would put it
-        # straight into /api/status.
-        source = (ROOT / "oneagent" / "installer.py").read_text(encoding="utf-8")
-        readers = source.split("def _detected(", 1)[1].split("def _write_agent_config", 1)[0]
-        for forbidden in ["AUTH_TOKEN", "API_KEY", "apiKey", "api_key", "hasKey"]:
-            with self.subTest(field=forbidden):
-                # env_key is the variable *name* Codex reads from, not a value.
-                cleaned = readers.replace('"env_key"', "").replace("env_key", "")
-                self.assertNotIn(forbidden, cleaned)
-
-    def test_mirrors_are_public_read_only_registries_not_our_own_storage(self):
-        # An authorised mirror is permitted; redistributing a proprietary Agent
-        # from storage we run is not. Enforced here as well as in the install
-        # contract because it is a distribution rule, not an install detail.
-        for mirror_id, meta in catalog.PACKAGE_MIRRORS.items():
-            with self.subTest(mirror=mirror_id):
-                self.assertTrue(str(meta["registry"]).startswith("https://"))
-                self.assertTrue(str(meta["upstream"]).startswith("https://"))
-                for forbidden in ("oneagent", "maimory"):
-                    self.assertNotIn(forbidden, str(meta["registry"]).lower())
-
-    def test_frontend_output_may_not_reference_a_cdn(self):
-        # The policy forbids CDN and remote-font references in frontend output,
-        # but only source maps were ever checked. Agent marks are inlined for
-        # this reason, and nothing should quietly start fetching one instead.
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-
-            def archive_with(name: str, body: bytes) -> Path:
-                path = root / f"OneAgent-{abs(hash(body)) % 10**6}.zip"
-                with zipfile.ZipFile(path, "w") as archive:
-                    archive.writestr("OneAgent/agents.lock.json", "{}")
-                    archive.writestr("OneAgent/THIRD_PARTY_NOTICES.md", "notices")
-                    archive.writestr(name, body)
-                return path
-
-            remote = archive_with(
-                "OneAgent/frontend/dist/assets/app.js",
-                b'var a="<img src=\'https://cdn.example/mark.svg\'>"',
-            )
-            self.assertTrue(
-                any("remote asset reference" in problem for problem in inspect_zip(remote))
-            )
-
-            font = archive_with(
-                "OneAgent/frontend/dist/assets/app.css",
-                b'@import url("https://fonts.googleapis.com/css?family=Inter");',
-            )
-            self.assertTrue(any("remote asset reference" in problem for problem in inspect_zip(font)))
-
-            # An inlined mark and an XML namespace are not resource loads, and a
-            # link in copy is only a link — none may trip the scan.
-            clean = archive_with(
-                "OneAgent/frontend/dist/assets/app.js",
-                b'var a="data:image/svg+xml,%3Csvg xmlns=\'http://www.w3.org/2000/svg\'%3E"',
-            )
-            self.assertEqual(
-                [p for p in inspect_zip(clean) if "remote asset" in p],
-                [],
-            )
-
-    def test_release_manifest_checks_artifact_and_checksum_integrity(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-            artifact = root / "OneAgent-1.0.0-technical-preview-unsigned-linux-x64.zip"
-            lock = {
-                "schema_version": 1,
-                "agents": {"codex": {"package": {"version": "1.2.3"}}},
-            }
-            with zipfile.ZipFile(artifact, "w") as archive:
-                archive.writestr("OneAgent/agents.lock.json", json.dumps(lock))
-                archive.writestr("OneAgent/THIRD_PARTY_NOTICES.md", "notices")
-
-            digest = hashlib.sha256(artifact.read_bytes()).hexdigest()
-            manifest = root / "release-manifest-linux-x64.json"
-            payload = {
-                "schema_version": 1,
-                "channel": "technical-preview-unsigned",
-                "unsigned": True,
-                "agent_versions": {"codex": "1.2.3"},
-                "artifacts": [{"file": artifact.name, "sha256": digest, "bytes": artifact.stat().st_size}],
-            }
-            manifest.write_text(json.dumps(payload), encoding="utf-8")
-            manifest_digest = hashlib.sha256(manifest.read_bytes()).hexdigest()
-            checksum = root / "SHA256SUMS-linux-x64.txt"
-            checksum.write_text(
-                f"{digest}  {artifact.name}\n{manifest_digest}  {manifest.name}\n",
-                encoding="utf-8",
-            )
-            self.assertEqual(validate_manifest(manifest), [])
-
-            payload["artifacts"][0]["sha256"] = "0" * 64
-            manifest.write_text(json.dumps(payload), encoding="utf-8")
-            problems = validate_manifest(manifest)
-            self.assertTrue(any("artifact checksum mismatch" in problem for problem in problems))
-            self.assertTrue(any("checksum file mismatch" in problem for problem in problems))
-
-
-class LockIsTheSourceOfTruthTests(unittest.TestCase):
-    """Behaviour must be derived from agents.lock.json, not restated in Python.
-
-    The defect that motivated this suite: a fact lived in two places (the lock
-    and a hardcoded id set), the lock changed, and the behaviour did not. Each
-    test iterates the manifest and asserts the runtime follows whatever it
-    declares, so a new Agent added only to the lock works without a code edit.
-    """
-
-    def test_backups_are_derived_from_each_agents_config_path(self):
-        manifest = load_manifest()
-        auto_with_config = [
-            agent_id
-            for agent_id, meta in manifest["agents"].items()
-            if meta.get("config_mode") == "auto" and meta.get("config_path")
-        ]
-        # More than the two the payload used to hardcode, or the test proves
-        # nothing about generalisation.
-        self.assertGreater(len(auto_with_config), 2)
-        with tempfile.TemporaryDirectory() as tmp:
-            home = Path(tmp)
-            runtime = Runtime.create(home=home, os_id="linux", which=lambda _name: None)
-            target = "opencode"
-            config_path = home / manifest["agents"][target]["config_path"]
-            config_path.parent.mkdir(parents=True, exist_ok=True)
-            (config_path.parent / f"{config_path.name}.backup-20260729").write_text("old", encoding="utf-8")
-
-            backups = status_payload(runtime)["backups"]
-            # Every auto Agent with a config_path is a key, and only the one with
-            # a backup on disk reports True -- the glob came from config_path.
-            for agent_id in auto_with_config:
-                self.assertIn(agent_id, backups)
-                self.assertEqual(backups[agent_id], agent_id == target, agent_id)
-
-    def test_windows_install_gating_follows_windows_prerequisites(self):
-        manifest = load_manifest()
-        gated = {
-            agent_id
-            for agent_id, meta in manifest["agents"].items()
-            if meta.get("windows_prerequisites")
-        }
-        self.assertIn("claude-code", gated)
-        with tempfile.TemporaryDirectory() as tmp:
-            # npm present, every prerequisite absent: only Agents that declare a
-            # Windows prerequisite lose canInstall.
-            runtime = Runtime.create(
-                home=Path(tmp),
-                os_id="windows",
-                which=lambda name: "npm.cmd" if name == "npm" else None,
-                env={"USERPROFILE": tmp},
-            )
-            can_install = status_payload(runtime)["capabilities"]["canInstall"]
-            for agent_id, meta in manifest["agents"].items():
-                if meta.get("config_mode") != "auto" or (meta.get("package") or {}).get("manager") != "npm":
-                    continue
-                with self.subTest(agent=agent_id):
-                    self.assertEqual(can_install[agent_id], agent_id not in gated)
-
-    def test_providers_module_decides_by_protocol_not_agent_id(self):
-        # provider_config_base used to compare the adapter against "claude-code";
-        # the inference protocol is the real input. Restating an Agent id here
-        # would silently re-couple providers.py to the lock's identifiers.
-        source = (ROOT / "oneagent" / "providers.py").read_text(encoding="utf-8")
-        self.assertNotIn('"claude-code"', source)
-        self.assertNotIn("'claude-code'", source)
-
-
-if __name__ == "__main__":
-    unittest.main()
diff --git a/tests/test_server.py b/tests/test_server.py
deleted file mode 100644
index 48660fb8..00000000
--- a/tests/test_server.py
+++ /dev/null
@@ -1,570 +0,0 @@
-from __future__ import annotations
-
-import http.cookiejar
-import json
-import os
-import tempfile
-import threading
-import time
-import unittest
-from http.server import BaseHTTPRequestHandler, HTTPServer
-from pathlib import Path
-from types import SimpleNamespace
-from unittest.mock import patch
-from urllib.error import HTTPError
-from urllib.request import HTTPCookieProcessor, Request, build_opener
-
-from oneagent.errors import OneAgentError
-from oneagent.installer import Runtime
-from oneagent.server import (
-    MAX_BODY_BYTES,
-    OneAgentHTTPServer,
-    create_server,
-    main as server_main,
-    read_json,
-)
-from tests.support import LocalHTTPServer
-
-
-class ProviderHandler(BaseHTTPRequestHandler):
-    def log_message(self, *_args):
-        return
-
-    def _status(self):
-        authorization = self.headers.get("Authorization", "")
-        if "key-401" in authorization:
-            return 401
-        if "key-403" in authorization:
-            return 403
-        if "key-500" in authorization:
-            return 500
-        if "key-timeout" in authorization:
-            time.sleep(0.3)
-        if self.path.endswith("/models") and "key-404" in authorization:
-            return 404
-        if self.path.endswith("/models") and "key-405" in authorization:
-            return 405
-        return 200
-
-    def do_GET(self):
-        status = self._status()
-        self.send_response(status)
-        self.send_header("Content-Type", "application/json")
-        self.end_headers()
-        try:
-            if status == 200 and "key-list" in self.headers.get("Authorization", ""):
-                self.wfile.write(b'[{"id":"model-list"}]')
-            elif status == 200:
-                self.wfile.write(b'{"data":[{"id":"model-a"},{"id":"model-b"}]}')
-            else:
-                self.wfile.write(b'{"error":"provider error"}')
-        except BrokenPipeError:
-            pass
-
-    def do_POST(self):
-        status = self._status()
-        self.send_response(status)
-        self.send_header("Content-Type", "application/json")
-        self.end_headers()
-        try:
-            self.wfile.write(b'{"ok":true}')
-        except BrokenPipeError:
-            pass
-
-
-class LocalServer:
-    def __init__(self, server):
-        self.server = server
-        self.thread = threading.Thread(target=server.serve_forever, daemon=True)
-
-    def __enter__(self):
-        self.thread.start()
-        return self.server
-
-    def __exit__(self, *_args):
-        self.server.shutdown()
-        self.server.server_close()
-        self.thread.join(timeout=5)
-
-
-def request_json(opener, url, payload=None, *, origin=None):
-    headers = {}
-    data = None
-    if payload is not None:
-        data = json.dumps(payload).encode()
-        headers["Content-Type"] = "application/json"
-    if origin:
-        headers["Origin"] = origin
-    request = Request(url, data=data, headers=headers, method="POST" if payload is not None else "GET")
-    try:
-        with opener.open(request, timeout=2) as response:
-            return response.status, dict(response.headers), json.loads(response.read().decode())
-    except HTTPError as exc:
-        try:
-            return exc.code, dict(exc.headers), json.loads(exc.read().decode())
-        finally:
-            exc.close()
-
-
-class ServerContractTests(unittest.TestCase):
-    def setUp(self):
-        self.tmp = tempfile.TemporaryDirectory()
-        self.root = Path(self.tmp.name)
-        self.static = self.root / "dist"
-        (self.static / "assets").mkdir(parents=True)
-        (self.static / "index.html").write_text("<!doctype html><div id='root'></div>", encoding="utf-8")
-        (self.static / "assets" / "app-DiZRmN5o.js").write_text("console.log('ok')", encoding="utf-8")
-        (self.static / "assets" / "payload.bin").write_bytes(b"not an allowed web asset")
-        self.home = self.root / "home"
-        self.home.mkdir()
-        self.runtime = Runtime.create(home=self.home, os_id="linux", which=lambda _name: None)
-        self.server = create_server("127.0.0.1", 0)
-        self.base = f"http://127.0.0.1:{self.server.server_port}"
-        self.origin = self.base
-        self.cookies = http.cookiejar.CookieJar()
-        self.opener = build_opener(HTTPCookieProcessor(self.cookies))
-        self.patches = [
-            patch("oneagent.server.static_root", return_value=self.static),
-            patch("oneagent.server._runtime", return_value=self.runtime),
-            patch.dict(os.environ, {"ONEAGENT_DISABLE_BROWSER": "1"}),
-        ]
-        for item in self.patches:
-            item.start()
-        self.local = LocalServer(self.server)
-        self.local.__enter__()
-
-    def tearDown(self):
-        self.local.__exit__(None, None, None)
-        for item in reversed(self.patches):
-            item.stop()
-        self.tmp.cleanup()
-
-    def bootstrap(self):
-        with self.opener.open(self.base + "/", timeout=2) as response:
-            self.assertEqual(response.status, 200)
-            self.assertIn("default-src 'self'", response.headers["Content-Security-Policy"])
-            self.assertEqual(response.headers["Cache-Control"], "no-store")
-        self.assertTrue(any(cookie.name == "oneagent_session" and cookie.value for cookie in self.cookies))
-
-    def post(self, path, payload, *, origin=True):
-        return request_json(self.opener, self.base + path, payload, origin=self.origin if origin is True else origin)
-
-    def test_status_is_additive_and_does_not_require_session(self):
-        status, _, payload = request_json(self.opener, self.base + "/api/status")
-        self.assertEqual(status, 200)
-        self.assertEqual(payload["apiVersion"], 1)
-        self.assertEqual(payload["platform"]["os"], "linux")
-        self.assertEqual(payload["agents"]["codex"]["lockedVersion"], "0.145.0")
-        self.assertIn("capabilities", payload)
-
-    def test_status_exposes_only_public_provider_fields(self):
-        # The payload used to send the PROVIDERS constant wholesale, so adding
-        # an internal key leaked it to every client: fallback_probe_model
-        # appeared in /api/status while the frontend type never declared it.
-        _, _, payload = request_json(self.opener, self.base + "/api/status")
-        for provider_id, meta in payload["providers"].items():
-            with self.subTest(provider=provider_id):
-                self.assertEqual(
-                    set(meta) - {"anthropic_base_url"},
-                    {"name", "home", "base_url"},
-                )
-        self.assertNotIn("fallback_probe_model", json.dumps(payload))
-
-    def test_bind_does_not_perform_reverse_dns_lookup(self):
-        # http.server's default server_bind() calls socket.getfqdn(), which blocks
-        # until it times out on hosts with no reverse resolver. That stalled GUI
-        # startup by ~70s on CI runners and would do the same on offline machines.
-        with patch("socket.getfqdn", side_effect=AssertionError("reverse DNS lookup during bind")) as getfqdn:
-            server = create_server("127.0.0.1", 0)
-            try:
-                self.assertEqual(server.server_name, "127.0.0.1")
-                self.assertEqual(server.server_port, server.socket.getsockname()[1])
-            finally:
-                server.server_close()
-        getfqdn.assert_not_called()
-
-    def test_server_refuses_to_bind_outside_localhost(self):
-        # The whole security model assumes a loopback-only listener: the Origin
-        # allowlist and the session cookie are meaningless if the socket is
-        # reachable from the network. Nothing covered this guard, so dropping
-        # it in a refactor would have kept the suite green.
-        for host in ("0.0.0.0", "::", "192.168.1.10", "localhost", ""):
-            with self.subTest(host=host):
-                with self.assertRaises(OneAgentError) as refused:
-                    create_server(host, 0)
-                self.assertEqual(refused.exception.code, "INVALID_REQUEST")
-                self.assertIn("127.0.0.1", refused.exception.message)
-
-    def test_main_reports_a_rejected_host_without_a_traceback(self):
-        # serve_forever is stubbed so that a missing guard fails this test
-        # immediately. Left unstubbed, main() would bind 0.0.0.0 and block, and
-        # the regression would surface as a CI job timeout rather than a
-        # failure naming the cause.
-        with patch("oneagent.server.webbrowser.open") as browser, patch.object(
-            OneAgentHTTPServer,
-            "serve_forever",
-            side_effect=AssertionError("main() must reject a non-loopback host before serving"),
-        ):
-            with self.assertRaises(SystemExit) as exited:
-                server_main(["--host", "0.0.0.0"])
-        self.assertIn("127.0.0.1", str(exited.exception))
-        browser.assert_not_called()
-
-    def test_missing_frontend_build_serves_a_readable_page(self):
-        # Running the GUI from a source checkout before `npm run build` must
-        # explain itself rather than surface a 404 or a traceback.
-        with tempfile.TemporaryDirectory() as empty:
-            with patch("oneagent.server.static_root", return_value=Path(empty)):
-                try:
-                    self.opener.open(self.base + "/", timeout=2)
-                    self.fail("expected HTTP 503")
-                except HTTPError as exc:
-                    body = exc.read().decode()
-                    self.assertEqual(exc.code, 503)
-                    self.assertIn("frontend build is missing", body)
-                    self.assertEqual(exc.headers["Cache-Control"], "no-store")
-                    self.assertIn("oneagent_session=", exc.headers["Set-Cookie"])
-                    self.assertIn("HttpOnly", exc.headers["Set-Cookie"])
-                    exc.close()
-
-    def test_post_requires_origin_and_session_cookie(self):
-        status, _, payload = self.post("/api/models", {"provider": "ppio", "api_key": "x"}, origin=self.origin)
-        self.assertEqual(status, 403)
-        self.assertEqual(payload["error_code"], "INVALID_ORIGIN")
-        self.bootstrap()
-        status, _, payload = self.post("/api/models", {"provider": "ppio", "api_key": "x"}, origin=False)
-        self.assertEqual(status, 403)
-        self.assertEqual(payload["error_code"], "INVALID_ORIGIN")
-        status, _, payload = self.post("/api/models", {"provider": "ppio", "api_key": "x"}, origin="http://127.0.0.1:1")
-        self.assertEqual(status, 403)
-        self.assertEqual(payload["error_code"], "INVALID_ORIGIN")
-
-    def test_static_assets_have_safe_cache_and_traversal_is_rejected(self):
-        self.bootstrap()
-        with self.opener.open(self.base + "/assets/app-DiZRmN5o.js", timeout=2) as response:
-            self.assertIn("immutable", response.headers["Cache-Control"])
-            self.assertEqual(response.headers["X-Content-Type-Options"], "nosniff")
-        with self.assertRaises(HTTPError) as blocked_type:
-            self.opener.open(self.base + "/assets/payload.bin", timeout=2)
-        self.assertEqual(blocked_type.exception.code, 404)
-        blocked_type.exception.close()
-        with self.assertRaises(HTTPError) as error:
-            self.opener.open(self.base + "/%2e%2e/agents.lock.json", timeout=2)
-        self.assertEqual(error.exception.code, 404)
-        error.exception.close()
-
-    def test_json_body_rejects_invalid_negative_and_oversized_lengths(self):
-        class RejectRead:
-            def read(self, _length):
-                raise AssertionError("invalid Content-Length must be rejected before reading the body")
-
-        for value in ["not-a-number", "-1", str(MAX_BODY_BYTES + 1)]:
-            with self.subTest(content_length=value):
-                handler = SimpleNamespace(headers={"Content-Length": value}, rfile=RejectRead())
-                with self.assertRaises(OneAgentError):
-                    read_json(handler)
-
-    def test_register_urls_and_invalid_provider(self):
-        self.bootstrap()
-        status, _, payload = self.post("/api/open-register", {"provider": "ppio", "agents": ["codex"]})
-        self.assertEqual(status, 200)
-        self.assertTrue(payload["url"].startswith("https://ppio.com/?"))
-        status, _, payload = self.post("/api/open-register", {"provider": "novita", "agents": ["aider"]})
-        self.assertEqual(status, 200)
-        self.assertTrue(payload["url"].startswith("https://novita.ai/?"))
-        status, _, payload = self.post("/api/open-register", {"provider": "custom"})
-        self.assertEqual(status, 400)
-        self.assertEqual(payload["error_code"], "INVALID_REQUEST")
-
-    def test_probe_and_models_map_provider_failures(self):
-        provider = LocalHTTPServer(("127.0.0.1", 0), ProviderHandler)
-        with LocalServer(provider):
-            custom_base = f"http://127.0.0.1:{provider.server_port}"
-            self.bootstrap()
-            for key, expected in [("key-401", "API_KEY_REJECTED"), ("key-403", "API_KEY_REJECTED"), ("key-500", "PROVIDER_UNREACHABLE")]:
-                with self.subTest(key=key):
-                    status, _, payload = self.post(
-                        "/api/probe",
-                        {"provider": "custom", "api_base_url": custom_base, "api_key": key, "model": "m"},
-                    )
-                    self.assertEqual(status, 200)
-                    self.assertEqual(payload["error_code"], expected)
-            for key, expected in [("key-404", "MODELS_UNSUPPORTED"), ("key-405", "MODELS_UNSUPPORTED"), ("key-500", "PROVIDER_UNREACHABLE")]:
-                with self.subTest(key=key):
-                    status, _, payload = self.post(
-                        "/api/models",
-                        {"provider": "custom", "api_base_url": custom_base, "api_key": key},
-                    )
-                    self.assertEqual(status, 200)
-                    self.assertEqual(payload["error_code"], expected)
-            status, _, payload = self.post(
-                "/api/models",
-                {"provider": "custom", "api_base_url": custom_base, "api_key": "key-200"},
-            )
-            self.assertEqual(status, 200)
-            self.assertEqual(payload["models"], ["model-a", "model-b"])
-            status, _, payload = self.post(
-                "/api/models",
-                {"provider": "custom", "api_base_url": custom_base, "api_key": "key-list"},
-            )
-            self.assertEqual(status, 200)
-            self.assertEqual(payload["models"], ["model-list"])
-
-    def test_probe_tests_the_protocol_of_each_selected_agent(self):
-        calls: list[tuple[str, str]] = []
-
-        def fake_probe(*, protocol, model, **_kwargs):
-            calls.append((protocol, model))
-            # Mirror the real endpoint: the model serves chat but refuses Responses.
-            if protocol == "responses":
-                return {
-                    "ok": False, "reachable": True, "protocol": protocol, "status": 400,
-                    "message": "does not support OpenAI Responses",
-                    "error_code": "PROTOCOL_UNSUPPORTED", "retryable": False,
-                }
-            return {
-                "ok": True, "reachable": True, "protocol": protocol, "status": 200,
-                "message": "passed", "error_code": None, "retryable": False,
-            }
-
-        self.bootstrap()
-        with patch("oneagent.server.protocol_probe", side_effect=fake_probe):
-            # Codex alone -> Responses only, and the refusal must surface.
-            _, _, payload = self.post(
-                "/api/probe",
-                {"provider": "custom", "api_base_url": "https://x.test/v1", "api_key": "k",
-                 "model": "glm", "agents": ["codex"]},
-            )
-            self.assertFalse(payload["ok"])
-            self.assertEqual(payload["error_code"], "PROTOCOL_UNSUPPORTED")
-            self.assertEqual(sorted(payload["protocols"]), ["responses"])
-
-            calls.clear()
-            # OpenCode alone speaks Chat Completions, so the same model passes.
-            _, _, payload = self.post(
-                "/api/probe",
-                {"provider": "custom", "api_base_url": "https://x.test/v1", "api_key": "k",
-                 "model": "glm", "agents": ["opencode"]},
-            )
-            self.assertTrue(payload["ok"])
-            self.assertEqual(sorted(payload["protocols"]), ["openai"])
-
-            calls.clear()
-            # Mixed selection: every distinct protocol probed once, and the
-            # failing one is reported even though another succeeded.
-            _, _, payload = self.post(
-                "/api/probe",
-                {"provider": "custom", "api_base_url": "https://x.test/v1", "api_key": "k",
-                 "model": "glm", "agents": ["codex", "opencode", "kilo-cli", "openclaw"]},
-            )
-            self.assertEqual(sorted(p for p, _ in calls), ["openai", "responses"])
-            self.assertFalse(payload["ok"])
-            self.assertEqual(payload["error_code"], "PROTOCOL_UNSUPPORTED")
-
-            calls.clear()
-            # No agents -> unchanged OpenAI-compatible behaviour for older clients.
-            _, _, payload = self.post(
-                "/api/probe",
-                {"provider": "custom", "api_base_url": "https://x.test/v1", "api_key": "k", "model": "glm"},
-            )
-            self.assertEqual([p for p, _ in calls], ["openai"])
-            self.assertTrue(payload["ok"])
-
-    def test_provider_timeout_is_retryable(self):
-        provider = LocalHTTPServer(("127.0.0.1", 0), ProviderHandler)
-        with LocalServer(provider), patch.dict(os.environ, {"ONEAGENT_HTTP_TIMEOUT": "0.05"}):
-            self.bootstrap()
-            status, _, payload = self.post(
-                "/api/probe",
-                {
-                    "provider": "custom",
-                    "api_base_url": f"http://127.0.0.1:{provider.server_port}",
-                    "api_key": "key-timeout",
-                    "model": "m",
-                },
-            )
-            self.assertEqual(status, 200)
-            self.assertEqual(payload["error_code"], "TIMEOUT")
-            self.assertTrue(payload["retryable"])
-
-    def test_install_writes_profile_without_leaking_key(self):
-        self.bootstrap()
-        secret = "sentinel-api-secret"
-        status, _, payload = self.post(
-            "/api/install",
-            {
-                "agents": ["codex", "openclaw"],
-                "provider": "ppio",
-                "api_key": secret,
-                "model": "model-a",
-                "configure": True,
-                "install_agent": False,
-                "skip_test": True,
-            },
-        )
-        self.assertEqual(status, 200)
-        self.assertTrue(payload["ok"])
-        self.assertNotIn(secret, json.dumps(payload))
-        profile = json.loads((self.home / ".oneagent" / "profiles" / "default.json").read_text(encoding="utf-8"))
-        self.assertEqual(profile["agent_ids"], ["codex", "openclaw"])
-        self.assertNotIn(secret, json.dumps(profile))
-
-    def test_existing_account_mode_runs_agent_workflow_and_writes_profile(self):
-        self.bootstrap()
-        status, _, payload = self.post(
-            "/api/install",
-            {
-                "agents": ["codex"],
-                "configure": False,
-                "install_agent": False,
-            },
-        )
-        self.assertEqual(status, 200)
-        self.assertTrue(payload["ok"])
-        self.assertEqual(payload["results"][0]["status"], "skipped")
-        self.assertIn("Model configuration skipped", payload["log"])
-        profile = json.loads((self.home / ".oneagent" / "profiles" / "default.json").read_text(encoding="utf-8"))
-        self.assertEqual(profile["config_mode"], "existing-account")
-        self.assertEqual(profile["provider"], "existing-account")
-        self.assertEqual(profile["agent_ids"], ["codex"])
-        self.assertIsNone(profile["base_url"])
-        self.assertIsNone(profile["model"])
-        self.assertFalse((self.home / ".oneagent" / "env").exists())
-
-    def test_unknown_agent_is_invalid_request(self):
-        self.bootstrap()
-        status, _, payload = self.post(
-            "/api/install",
-            {"agents": ["unknown"], "configure": False, "install_agent": False},
-        )
-        self.assertEqual(status, 400)
-        self.assertEqual(payload["error_code"], "INVALID_REQUEST")
-
-    def test_install_request_types_and_version_modes_are_strict(self):
-        self.bootstrap()
-        for payload in (
-            {"agents": [], "configure": False},
-            {"agents": ["codex"], "configure": "false"},
-            {"agents": ["codex"], "configure": False, "install_agent": 1},
-            {"agents": ["codex"], "configure": False, "timeout": 0},
-            {"agents": ["codex"], "configure": False, "locked_version": True, "latest": True},
-            {"agents": ["codex"], "profile_agents": ["opencode"], "configure": False},
-        ):
-            with self.subTest(payload=payload):
-                status, _, response = self.post("/api/install", payload)
-                self.assertEqual(status, 400)
-                self.assertEqual(response["error_code"], "INVALID_REQUEST")
-
-    def test_register_rejects_unknown_agent(self):
-        self.bootstrap()
-        status, _, payload = self.post("/api/open-register", {"provider": "ppio", "agents": ["unknown"]})
-        self.assertEqual(status, 400)
-        self.assertEqual(payload["error_code"], "INVALID_REQUEST")
-
-    def test_profiles_endpoint_lists_saved_profiles_without_key_material(self):
-        self.bootstrap()
-        status, _, body = request_json(self.opener, self.base + "/api/profiles")
-        self.assertEqual(status, 200)
-        self.assertEqual(body, {"ok": True, "profiles": [], "activeProfile": None})
-
-        secret = "sentinel-profile-key"
-        status, _, payload = self.post(
-            "/api/profiles",
-            {
-                "provider": "ppio",
-                "model": "deepseek-v3",
-                "agents": ["codex", "opencode"],
-                "api_key": secret,
-                "label": "PPIO DeepSeek",
-            },
-        )
-        self.assertEqual(status, 200)
-        self.assertEqual(payload["profile"]["id"], "ppio-deepseek-v3")
-        self.assertTrue(payload["profile"]["hasKey"])
-        self.assertNotIn(secret, json.dumps(payload))
-
-        # Saving stores a profile but does not activate it.
-        status, _, body = request_json(self.opener, self.base + "/api/profiles")
-        self.assertEqual(status, 200)
-        self.assertEqual([item["id"] for item in body["profiles"]], ["ppio-deepseek-v3"])
-        self.assertEqual(body["profiles"][0]["agentIds"], ["codex", "opencode"])
-        self.assertIsNone(body["activeProfile"])
-        self.assertNotIn(secret, json.dumps(body))
-
-    def test_activate_endpoint_repoints_one_agent_at_a_time(self):
-        self.bootstrap()
-        secret = "sentinel-activate-key"
-        status, _, first = self.post(
-            "/api/agents/codex/activate",
-            {"provider": "ppio", "model": "deepseek-v3", "api_key": secret},
-        )
-        self.assertEqual(status, 200)
-        self.assertEqual(first["agent"], "codex")
-        self.assertEqual(first["provider"], "ppio")
-        self.assertTrue(first["restart"])
-        self.assertNotIn(secret, json.dumps(first))
-
-        status, _, second = self.post(
-            "/api/agents/opencode/activate",
-            {"provider": "novita", "model": "qwen-max", "api_key": "other-key"},
-        )
-        self.assertEqual(status, 200)
-
-        # Status reports the two Agents independently.
-        status, _, body = request_json(self.opener, self.base + "/api/status")
-        self.assertEqual(body["agents"]["codex"]["provider"], "ppio")
-        self.assertEqual(body["agents"]["opencode"]["provider"], "novita")
-        self.assertNotIn(secret, json.dumps(body))
-
-    def test_activate_endpoint_rejects_bad_agents_and_enforces_origin(self):
-        self.bootstrap()
-        for agent_id, expected in (("cursor", 400), ("nope", 400), ("..%2Fescape", 400)):
-            with self.subTest(agent=agent_id):
-                status, _, body = self.post(
-                    f"/api/agents/{agent_id}/activate",
-                    {"provider": "ppio", "model": "m", "api_key": "k"},
-                )
-                self.assertEqual(status, expected)
-                self.assertFalse(body["ok"])
-        # A route that does not match the shape stays a 404, not a activation.
-        status, _, _ = self.post("/api/agents//activate", {"provider": "ppio"})
-        self.assertEqual(status, 404)
-
-    def test_profiles_endpoint_validates_input(self):
-        self.bootstrap()
-        for payload in (
-            {"provider": "ppio", "agents": ["codex"]},                # no model
-            {"provider": "ppio", "model": "m"},                       # no agents
-            {"provider": "nope", "model": "m", "agents": ["codex"]},  # unknown provider
-            {"profile_id": "../x", "provider": "ppio", "model": "m", "agents": ["codex"]},
-        ):
-            with self.subTest(payload=payload):
-                status, _, response = self.post("/api/profiles", payload)
-                self.assertEqual(status, 400)
-                self.assertEqual(response["error_code"], "INVALID_REQUEST")
-
-    def test_install_activates_the_default_profile(self):
-        self.bootstrap()
-        status, _, payload = self.post(
-            "/api/install",
-            {
-                "agents": ["codex"],
-                "provider": "ppio",
-                "api_key": "sentinel-install-key",
-                "model": "m",
-                "install_agent": False,
-                "skip_test": True,
-            },
-        )
-        self.assertEqual(status, 200)
-        self.assertTrue(payload["ok"])
-        status, _, body = request_json(self.opener, self.base + "/api/profiles")
-        self.assertEqual(status, 200)
-        self.assertEqual(body["activeProfile"], "default")
-        self.assertEqual([item["id"] for item in body["profiles"]], ["default"])
-        self.assertTrue(body["profiles"][0]["hasKey"])
-        self.assertNotIn("sentinel-install-key", json.dumps(body))
-
-
-if __name__ == "__main__":
-    unittest.main()