feat(install): add release-aware installers and explicit personal service setup

.github/workflows/installation.yml

@@ -0,0 +1,65 @@
+name: Script installation
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: installation-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  installation:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+
+      - name: Build the installation fixture
+        shell: bash
+        env:
+          # Qualify this commit using release-shaped metadata, without publishing it.
+          SETUPTOOLS_SCM_PRETEND_VERSION: "1.2.0"
+        run: uv build --wheel --out-dir dist/installation
+
+      - name: Check shared installer behavior and source resolution
+        shell: bash
+        run: >-
+          uv run --no-sync pytest -q tests/test_installation_contract.py tests/native/test_install_sources.py
+          --junitxml "$RUNNER_TEMP/installation-contract.xml"
+          --basetemp "$RUNNER_TEMP/installation-contract-tests"
+
+      - name: Exercise bootstrap, version selection, profiles, and persistent memory
+        shell: bash
+        env:
+          POWERCONTEXT_INSTALL_WHEEL: ${{ github.workspace }}/dist/installation/powercontext-1.2.0-py3-none-any.whl
+        run: >-
+          uv run --no-sync pytest -q tests/native/test_installation.py
+          --junitxml "$RUNNER_TEMP/installation.xml"
+          --basetemp "$RUNNER_TEMP/installation-tests"
+
+      - name: Upload installation diagnostics after failure
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: installation-${{ matrix.os }}
+          path: |
+            ${{ runner.temp }}/installation.xml
+            ${{ runner.temp }}/installation-contract.xml
+            ${{ runner.temp }}/installation-tests/**/*.log
+          if-no-files-found: ignore

.github/workflows/native-service.yml

@@ -44,6 +44,8 @@ jobs:
           echo "DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u)/bus" >> "$GITHUB_ENV"
 
       - name: Install the built distribution in a fresh virtual environment
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: "1.2.0"
         shell: bash
         run: |
           uv build --wheel
@@ -58,6 +60,16 @@ jobs:
           --basetemp "$RUNNER_TEMP/powercontext-native-tests"
           tests/native/test_personal_service_lifecycle.py
 
+      - name: Exercise script installation and service reconciliation
+        env:
+          POWERCONTEXT_INSTALL_WHEEL: ${{ github.workspace }}/dist/powercontext-1.2.0-py3-none-any.whl
+        shell: bash
+        run: >-
+          .native-venv/bin/python -m pytest -q
+          --junitxml "$RUNNER_TEMP/installer-service.xml"
+          --basetemp "$RUNNER_TEMP/installer-service-tests"
+          tests/native/test_service_installation.py
+
       - name: Report Linux lifecycle failures
         if: failure()
         run: >-
@@ -76,7 +88,10 @@ jobs:
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
         with:
           name: linux-native-service-logs
-          path: ${{ runner.temp }}/powercontext-native-tests/**/logs/*
+          path: |
+            ${{ runner.temp }}/powercontext-native-tests/**/logs/*
+            ${{ runner.temp }}/installer-service-tests/**/*.log
+            ${{ runner.temp }}/installer-service.xml
           if-no-files-found: ignore
 
   macos-launchagent:
@@ -97,6 +112,8 @@ jobs:
         uses: ./.github/actions/setup-python-env
 
       - name: Install the built distribution in a fresh virtual environment
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: "1.2.0"
         shell: bash
         run: |
           uv build --wheel
@@ -113,6 +130,16 @@ jobs:
           --basetemp "$RUNNER_TEMP/powercontext-native-tests"
           tests/native/test_personal_service_lifecycle.py
 
+      - name: Exercise script installation and service reconciliation
+        env:
+          POWERCONTEXT_INSTALL_WHEEL: ${{ github.workspace }}/dist/powercontext-1.2.0-py3-none-any.whl
+        shell: bash
+        run: >-
+          .native-venv/bin/python -m pytest -q
+          --junitxml "$RUNNER_TEMP/installer-service.xml"
+          --basetemp "$RUNNER_TEMP/installer-service-tests"
+          tests/native/test_service_installation.py
+
       - name: Report macOS lifecycle failures
         if: failure()
         run: >-
@@ -129,7 +156,10 @@ jobs:
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
         with:
           name: macos-native-service-logs
-          path: ${{ runner.temp }}/powercontext-native-tests/**/logs/*
+          path: |
+            ${{ runner.temp }}/powercontext-native-tests/**/logs/*
+            ${{ runner.temp }}/installer-service-tests/**/*.log
+            ${{ runner.temp }}/installer-service.xml
           if-no-files-found: ignore
 
   windows-task-scheduler:

docs/en/docs/get-started/install-and-run.md

@@ -22,6 +22,151 @@ Windows CLI, Server, and personal-service support is experimental. Each Agent Ho
 requirements. Examples using Bash syntax require a Bash environment and cannot be pasted directly into PowerShell.
 Embedded seekDB is unavailable on Windows.
 
+## Install with the recommended script
+
+The script installs the CLI and local Server in an isolated uv tool environment. It reuses compatible uv/Python,
+or installs uv and Python 3.12 in user-owned directories. It does not need administrator privileges.
+
+macOS or Linux (Bash; `curl` or `wget` is required):
+
+```bash
+curl -fsSL https://powercontext.oceanbase.io/install.sh | bash
+```
+
+Windows (PowerShell 5.1 or newer):
+
+```powershell
+powershell -ExecutionPolicy Bypass -c "& ([scriptblock]::Create((irm https://powercontext.oceanbase.io/install.ps1)))"
+```
+
+Apply the PATH command printed at completion before running `powercontext` in your terminal. The installer does not
+edit shell startup files or the persistent Windows PATH. `UV_INSTALL_DIR` selects where a missing uv is installed;
+`UV_TOOL_BIN_DIR` selects the PowerContext executable directory.
+
+Installation runs unattended by default. Pass `--host codex` (repeatable) to install selected Agent integrations.
+Only Agent setup needs Git and each host's prerequisites. `--no-hosts` remains an optional way to state the default;
+it cannot be combined with `--host`. The [capability matrix](../integrations/capabilities.md) describes host support.
+
+For an existing remote Server, add `--profile client` to install only the CLI and Client dependencies. The default
+`--profile local` includes the local Server. Neither profile starts a Server, registers a service, or overwrites
+configuration or data. For a local installation, continue with `powercontext config init` and [Quick Start](quickstart.md).
+Client-only installations use endpoint settings in the [remote connection guide](../operate/connect-remote-server.md).
+
+## Configure and install a personal service
+
+For personal macOS/Linux use, the recommended lifecycle is a native current-user service. The installer can
+explicitly compose configuration and service registration:
+
+```bash
+curl -fsSL https://powercontext.oceanbase.io/install.sh | bash -s -- \
+  --configure --service --env-file "$HOME/.config/powercontext/powercontext.env"
+```
+
+`--configure` opens the existing wizard through the controlling terminal and requires `--env-file`. Save the file
+to continue; cancellation stops service and host setup. Choose loopback binding for a personal service. Linux needs
+an available `systemd --user` manager. In a non-interactive environment, provide an existing protected file instead:
+
+```bash
+curl -fsSL https://powercontext.oceanbase.io/install.sh | bash -s -- \
+  --service --env-file /path/to/powercontext.env
+```
+
+The installer validates that file, runs `service install`, checks `service status`, and runs `doctor --env-file`
+against the Server settings in the same file. An explicit `--host` also receives this file and the installed release
+ref. Client-only installations reject `--configure` and `--service` before installation. `--env-file` alone can supply
+connection settings to an explicitly selected host without installing a local service.
+
+Windows supports the same explicit options experimentally; `--service` opts into login auto-start. Run `--configure`
+in an interactive console. Protect an existing file using the ACL steps in [Deploy the Server](../operate/deploy-server.md).
+
+These options need an installed release providing `config init --require-write` and `doctor --env-file`. If the selected
+release lacks them, the installer reports the failed stage and retains the Runtime; use a compatible release or the
+separate configuration/service commands. Runtime installation, saved configuration, service registration, and Server
+readiness are separate outcomes. `degraded` diagnostics return nonzero. A failed post-install stage does not roll back
+packages, delete configuration, or remove an already committed service registration.
+
+After any file edit, including writing returned Scope IDs, reconcile using the original file:
+
+```bash
+powercontext service install --env-file /path/to/powercontext.env
+powercontext service status
+powercontext doctor --env-file /path/to/powercontext.env
+```
+
+`doctor --env-file` gives the file authority over shell defaults. A Server file selects its listener; a client-only
+file selects its Client URL. `--server-url` can explicitly override the diagnostic target. Generated next-step instructions
+cover Scope creation and Agent acceptance; a running service does not establish an Agent workflow.
+
+## Installer version selection
+
+The default `--version latest` installs or upgrades to the newest stable release available from the selected index
+and compatible with the chosen Python. It excludes prereleases. `--version` accepts an exact release, including an
+explicit prerelease such as `1.3.0rc1`; it never substitutes a different version if that release is unavailable.
+
+For example, install PowerContext 1.4.0 with its Codex integration:
+
+```bash
+curl -fsSL https://powercontext.oceanbase.io/install.sh | bash -s -- --version 1.4.0 --host codex
+```
+
+This selects package `1.4.0` and Git tag `powercontext-v1.4.0`. With `latest`, the installer reads the installed CLI's
+version and uses its matching tag; it never uses the moving `master` branch for host setup. To add an integration later:
+
+```bash
+powercontext setup codex --ref "powercontext-v$(powercontext --version)"
+```
+
+Use `powercontext setup --ref "powercontext-v$(powercontext --version)"` for an interactive host picker.
+
+In PowerShell, the same double-quoted expression works. An integration failure leaves the installed Runtime usable
+and exits with an error and a retry instruction. Installation success does not establish Server readiness or host
+workflow correctness; use the checks below and the integration's own guide.
+
+The installer verifies the installed version and advertised commands before reporting success. A package can install
+successfully while command verification fails; in that case the old executable may already have been replaced. Review
+the named command error and rerun with a known working `--version`. The installer does not roll package files back.
+
+## Retry dependency downloads with a mirror
+
+Package indexes, uv binaries, and Python distributions are separate downloads. Changing the package index does not
+change the uv or Python download location.
+
+| Download | Explicit setting | Automatic China source | Global source |
+| --- | --- | --- | --- |
+| PowerContext and Python packages | `--index-url URL`, uv index environment variables or `uv.toml` | Tsinghua PyPI mirror | PyPI |
+| uv installer | `POWERCONTEXT_UV_INSTALLER_URL` | USTC uv release mirror | Astral installer |
+| uv binaries | `UV_DOWNLOAD_URL` or `UV_INSTALLER_GITHUB_BASE_URL` | USTC uv release mirror | Astral release channels |
+| Python distributions | `UV_PYTHON_INSTALL_MIRROR` | NJU python-build-standalone mirror | uv default channels |
+
+```bash
+curl -fsSL https://powercontext.oceanbase.io/install.sh | bash -s -- --region cn
+curl -fsSL https://powercontext.oceanbase.io/install.sh | bash -s -- --index-url https://pypi.org/simple
+```
+
+`--region auto|cn|global` overrides `POWERCONTEXT_INSTALL_REGION`. Auto selection uses a named local timezone, then the
+locale territory, then global; it makes no geolocation request. An unavailable automatic mirror can fall back to the
+official source. A reachable China package mirror remains selected even if it lacks the requested release; uv reports
+resolution or artifact failures without retrying against another index. Use `--region global` or an explicit source
+to select another index. Explicit sources never fall back automatically.
+A mirror may lag PyPI: `latest` means the newest compatible stable release on the chosen index.
+
+Existing uv index settings and configuration files take precedence over automatic package mirrors. An explicit
+`--index-url` overrides the default index only; additional uv indexes keep their priority. Private index credentials
+belong in uv's authentication configuration, not in script arguments. uv does not read `PIP_INDEX_URL` or
+`PIP_EXTRA_INDEX_URL`. Existing Python mirror settings and `uv.toml` also suppress automatic Python mirror selection.
+`UV_ASTRAL_MIRROR_URL` is passed through for uv versions that support it. These settings are scoped to the installation;
+your persistent package-manager configuration is unchanged. An existing uv is reused without upgrading it.
+
+To inspect the installer or pass several options in PowerShell, save it first:
+
+```powershell
+irm https://powercontext.oceanbase.io/install.ps1 -OutFile install.ps1
+powershell -ExecutionPolicy Bypass -File .\install.ps1 --region cn --version 1.4.0
+```
+
+Cached reinstallation with `UV_OFFLINE=1` can work when uv, compatible Python, and all required packages are already
+present. This is not an offline distribution bundle; missing downloads fail explicitly.
+
 ## Choose a version
 
 These instructions use PowerContext 1.4.0. Keep the package and Agent integration on