[PsiACE]

Which issue or RFC does this PR close?

Closes #1900. Refs #1733 and #1408. RFC: docs/en/rfcs/1892-script-installation.md / docs/zh/rfcs/1892-script-installation.md.

Rationale for this change

A fresh installation needs Python, uv, the correct package extras, and a matching Agent integration ref. Package indexes, uv binaries, and Python distributions also need separate download settings. The installers handle these prerequisites and version choices through existing uv and PowerContext commands.

What changes are included in this PR?

• Bash and PowerShell installers that reuse or provision prerequisites, select local/client dependencies, and install the latest stable or an exact release.
• Independent download settings and automatic regional mirrors. Agent setup runs only for selected hosts and uses the installed package's release tag.
• Stable-release selection that replaces an installed prerelease correctly on older uv versions.
• Shared installer contracts, controlled-index source tests, actual-wheel acceptance, and a Linux/macOS/Windows installation matrix gated by Main's preflight and required-result checks.
• Installation and personal-service instructions for users, design contracts in the existing RFC format, and fixture documentation for test contributors.

Are there any user-facing changes?

Users can install without first provisioning Python and uv. After installation, they configure the Server and register a personal service with the existing CLI. The guides follow that sequence and use platform tabs for installer commands. An integration failure retains the installed PowerContext and reports how to retry setup.

The CLI, configuration wizard, service implementation, and native service workflow match master. Windows support remains experimental.

How was this change tested?

• make check and CI admission/scope regression tests.
• npm exec --yes --package=pnpm@11.13.1 -- make docs-test.
• Installer contracts, source-resolution regressions with uv 0.10.12, and focused CLI and release-reference tests.
• Actual-wheel Linux acceptance covering installation, HTTP readiness, Memory persistence, offline piped reinstall, version selection, and profile replacement.
• Bash syntax and PowerShell parser checks. Native macOS/Windows execution and real service registration were not run locally.

AI usage statement

OpenAI Codex assisted with implementation, review, validation, and documentation.

[Copilot]

🔵 Needs a closer look

Native actual-wheel bootstrap acceptance is still pending, and parser checks and synthetic-wheel tests do not establish cross-platform prerequisite provisioning or installed CLI behavior.

No open issues 🎉

What changed in this PR

Adds release-aware installers that prepare Python and uv, install PowerContext, and optionally configure matching Agent integrations. Updates onboarding to recommend service-managed personal Servers while leaving CLI and service behavior unchanged.

Changes:

• Adds Bash and PowerShell installers with release selection, local/client profiles, and independent download-source settings.
• Adds shared installer contracts, controlled-index tests, actual-wheel acceptance, and a three-platform CI matrix.
• Documents installation, recovery, and separate configuration and personal-service registration.

File	Description
website/​public/​install.sh	Adds the macOS/Linux installer.
website/​public/​install.ps1	Adds the Windows installer.
tests/​test_release_version.py	Checks installer version examples during releases.
tests/​test_installation_contract.py	Runs shared behavior cases through native installers and real uv.
tests/​native/​test_installation.py	Tests actual-wheel installation, profiles, readiness, and persistence.
tests/​native/​test_install_sources.py	Tests source selection, fallback, and release resolution.
tests/​fixtures/​installation/​README.md	Documents fixture usage and test boundaries.
tests/​fixtures/​installation/​hosts.json	Defines host-selection and partial-failure cases.
tests/​fixtures/​installation/​capabilities.json	Defines command-verification and version-mismatch cases.
scripts/​release_version.py	Updates explicit installer versions in localized guides.
README.md	Links the installer and recommends personal services.
README_JP.md	Updates Japanese installation and service guidance.
README_CN.md	Updates Chinese installation and service guidance.
docs/​zh/​rfcs/​1892-script-installation.md	Defines the installer contract in Chinese.
docs/​zh/​docs/​get-started/​quickstart.md	Recommends service-managed startup in Chinese.
docs/​zh/​docs/​get-started/​install-and-run.md	Documents installation, mirrors, recovery, and services in Chinese.
docs/​en/​rfcs/​1892-script-installation.md	Defines the installer contract in English.
docs/​en/​docs/​get-started/​quickstart.md	Recommends service-managed startup in English.
docs/​en/​docs/​get-started/​install-and-run.md	Documents installation, mirrors, recovery, and services in English.
.github/​workflows/​installation.yml	Adds Linux, macOS, and Windows installation checks.

_{Review effort: Balanced}

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

4 open issues

• This conditional expression has precedence issues: on non-Windows platforms it can still select… · New
• Invoke-WebRequest -UseBasicParsing is not supported in PowerShell 6+ (pwsh) and will fail with a… · New
• Same issue as Save-Download: -UseBasicParsing will break under PowerShell 6+/pwsh. Make the… · New
• The curl download path follows redirects (--location) without restricting redirect protocols. To… · New

_{Review effort: Lite}

[Copilot]

🔵 Needs a closer look

The PowerShell installer can execute an HTTP payload after an HTTPS downgrade redirect, and incorrect UTF-8 decoding can break verification for Unicode paths on Windows PowerShell 5.1.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Prevent HTTPS-to-HTTP redirects when downloading the uv installer

website/​public/​install.ps1:75

On the supported Windows PowerShell 5.1 runtime, Invoke-WebRequest follows HTTPS-to-HTTP redirects. An HTTPS uv installer URL can therefore pass Assert-HttpsUrl, redirect to an unauthenticated HTTP payload, and have that payload executed by Install-UvIfMissing with -ExecutionPolicy Bypass. Enforce HTTPS on every redirect hop, or reject redirects, and cover this path with a Windows downgrade regression like the Bash transport tests.

Decode native command output as UTF-8 on Windows PowerShell 5.1

website/​public/​install.ps1:313

On Windows PowerShell 5.1 with a non-UTF-8 console encoding, capturing uv's UTF-8 output corrupts a non-ASCII UV_TOOL_BIN_DIR, so CLI verification fails after installation succeeds. The python find captures at lines 265 and 299 also affect Unicode interpreter paths. Configure UTF-8 decoding before capturing native output and restore the original console encoding in finally.

4 resolved since last review

• Same issue as Save-Download: -UseBasicParsing will break under PowerShell 6+/pwsh. Make the…
• Invoke-WebRequest -UseBasicParsing is not supported in PowerShell 6+ (pwsh) and will fail with a…
• This conditional expression has precedence issues: on non-Windows platforms it can still select…
• The curl download path follows redirects (--location) without restricting redirect protocols. To…

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The installer still allows HTTPS-to-HTTP redirects that can lead to execution of plaintext code and mishandles UTF-8 native output on Windows PowerShell 5.1, potentially breaking non-ASCII paths.

2 open issues

• Block HTTPS installer redirects to HTTP · New
• Capture PowerShell native output as UTF-8 · New

_{Review effort: Balanced}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.