diff --git a/.github/workflows/auto-release.yml b/.github/workflows/auto-release.yml
new file mode 100644
index 0000000..e9dd8cf
--- /dev/null
+++ b/.github/workflows/auto-release.yml
@@ -0,0 +1,129 @@
+name: Auto Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout validated main commit
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Resolve version
+        id: version
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="$(node -p "JSON.parse(require('fs').readFileSync('package.json','utf8')).version")"
+          tag="v${version}"
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+
+      - name: Inspect existing tag and release
+        id: existing
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "release_exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "release_exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+          if git ls-remote --exit-code --tags origin "refs/tags/$TAG" >/dev/null 2>&1; then
+            echo "tag_exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag_exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Verify release metadata
+        if: steps.existing.outputs.release_exists == 'false'
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          grep -q "^## ${VERSION}\b" CHANGELOG.md
+          grep -q "export const VERSION = \"${VERSION}\";" src/core.ts
+          grep -q "JEV_MCP_GIT_REF:-v${VERSION}" scripts/install.sh
+          grep -q "\"v${VERSION}\"" scripts/install.ps1
+
+      - name: Install locked dependencies
+        if: steps.existing.outputs.release_exists == 'false'
+        run: npm ci --no-audit --no-fund
+
+      - name: Re-run repository checks
+        if: steps.existing.outputs.release_exists == 'false'
+        run: npm run check
+
+      - name: Create annotated tag
+        if: >
+          steps.existing.outputs.release_exists == 'false' &&
+          steps.existing.outputs.tag_exists == 'false'
+        env:
+          TAG: ${{ steps.version.outputs.tag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "jev-mcp $TAG" "${{ github.event.workflow_run.head_sha }}"
+          git push origin "$TAG"
+
+      - name: Fetch release tag
+        if: steps.existing.outputs.release_exists == 'false'
+        env:
+          TAG: ${{ steps.version.outputs.tag }}
+        shell: bash
+        run: git fetch --force origin "refs/tags/$TAG:refs/tags/$TAG"
+
+      - name: Build release assets
+        if: steps.existing.outputs.release_exists == 'false'
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          TAG: ${{ steps.version.outputs.tag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p release-assets
+          git archive --format=zip --prefix="jev-mcp-${VERSION}/"             --output="release-assets/jev-mcp-${VERSION}.zip" "$TAG"
+          git archive --format=tar.gz --prefix="jev-mcp-${VERSION}/"             --output="release-assets/jev-mcp-${VERSION}.tar.gz" "$TAG"
+          sha256sum release-assets/jev-mcp-* > release-assets/SHA256SUMS.txt
+          awk -v version="$VERSION" '
+            $0 ~ "^## " version { found=1; next }
+            found && /^## / { exit }
+            found { print }
+          ' CHANGELOG.md > release-assets/RELEASE_NOTES.md
+          test -s release-assets/RELEASE_NOTES.md
+
+      - name: Create GitHub Release
+        if: steps.existing.outputs.release_exists == 'false'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          gh release create "$TAG"             release-assets/jev-mcp-*.zip             release-assets/jev-mcp-*.tar.gz             release-assets/SHA256SUMS.txt             --verify-tag             --notes-file release-assets/RELEASE_NOTES.md             --title "$TAG"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e3be11e..96b97bc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,9 +4,13 @@ All notable project changes are documented here.
 
 ## Unreleased
 
+## 0.5.0 — Multi-client one-click installation
+
 - Added cross-platform bootstrap installers that create/update a durable local
   runtime at `~/.jev-mcp/runtime` instead of relying on npm Git-package
   execution at every MCP startup.
+- Stable bootstrap installs now default to the `v0.5.0` tag; advanced users can
+  set `JEV_MCP_GIT_REF=main` to follow the development channel.
 - Added one-command setup for Codex, Claude Code, Kimi Code, ZCode, Cursor,
   Gemini CLI, Windsurf-compatible config, generic `.agents`, and
   project-scoped VS Code MCP configuration.
diff --git a/README.md b/README.md
index 1c7bef1..7b16621 100644
--- a/README.md
+++ b/README.md
@@ -102,34 +102,34 @@ macOS / Linux:
 
 ```bash
 # Codex
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
 
 # Claude Code
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- claude-code
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- claude-code
 
 # Kimi Code
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- kimi
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- kimi
 
 # ZCode
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- zcode
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- zcode
 
 # Cursor
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- cursor
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- cursor
 
 # Gemini CLI
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- gemini
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- gemini
 ```
 
 Windows PowerShell (replace `codex` with another target as needed):
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1))) -Target codex
 ```
 
 To configure every detected user-level client:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash
 ```
 
 The key is stored only in `~/.jev-mcp/.env`; client MCP configs contain no
@@ -259,8 +259,7 @@ consume provider credits.
 | API dependency | TypeSafe-hosted System One API |
 | Stability | pre-1.0; behavior may evolve |
 
-The project follows semantic versioning in spirit, but while it remains below
-`1.0.0`, minor releases may refine tool schemas or behavior. Breaking changes
+The project follows semantic versioning in spirit. Stable one-click installs are pinned to the current release tag (`v0.5.0`) rather than `main`; users who intentionally want development builds can set `JEV_MCP_GIT_REF=main`. While the project remains below `1.0.0`, minor releases may refine tool schemas or behavior. Breaking changes
 should be documented in [CHANGELOG.md](CHANGELOG.md) and migration notes.
 
 ## Documentation
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 3870b91..bddf4e1 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -81,34 +81,34 @@ macOS / Linux：
 
 ```bash
 # Codex
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
 
 # Claude Code
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- claude-code
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- claude-code
 
 # Kimi Code
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- kimi
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- kimi
 
 # ZCode
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- zcode
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- zcode
 
 # Cursor
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- cursor
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- cursor
 
 # Gemini CLI
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- gemini
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- gemini
 ```
 
 Windows PowerShell（把 `codex` 换成其他目标即可）：
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1))) -Target codex
 ```
 
 自动配置检测到的用户级客户端：
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash
 ```
 
 TypeSafe key 只保存在本机 `~/.jev-mcp/.env`，不会写入各 AI 的 MCP 配置；
@@ -223,7 +223,7 @@ npm run inspect
 | License | MIT |
 | npm 发布 | 主动禁用 |
 | 外部依赖 | TypeSafe-hosted System One API |
-| 稳定性 | pre-1.0，行为仍可能演进 |
+| 稳定性 | pre-1.0；一键安装默认固定到 `v0.5.0` 稳定 tag |
 
 ## 文档
 
diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md
index 6019661..2473691 100644
--- a/docs/INSTALLATION.md
+++ b/docs/INSTALLATION.md
@@ -33,43 +33,43 @@ they are changed.
 ### Codex
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
 ```
 
 ### Claude Code
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- claude-code
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- claude-code
 ```
 
 ### Kimi Code
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- kimi
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- kimi
 ```
 
 ### ZCode
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- zcode
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- zcode
 ```
 
 ### Cursor
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- cursor
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- cursor
 ```
 
 ### Gemini CLI
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- gemini
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- gemini
 ```
 
 ### All detected user-level clients
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash
 ```
 
 The `all` flow intentionally skips the project-scoped VS Code target. Run the
@@ -80,7 +80,7 @@ installer with `vscode` from the project that should receive `.vscode/mcp.json`.
 ### Codex
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1))) -Target codex
 ```
 
 Replace `codex` with `claude-code`, `kimi`, `zcode`, `cursor`,
@@ -89,7 +89,7 @@ Replace `codex` with `claude-code`, `kimi`, `zcode`, `cursor`,
 Configure all detected user-level clients:
 
 ```powershell
-irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1 | iex
+irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1 | iex
 ```
 
 ## What the bootstrap does
@@ -135,7 +135,7 @@ If you intentionally manage `TYPESAFE_API_KEY` outside jev-mcp, skip local
 credential creation:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex --skip-key
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex --skip-key
 ```
 
 The MCP process must then inherit `TYPESAFE_API_KEY` from its environment.
@@ -145,10 +145,10 @@ The MCP process must then inherit `TYPESAFE_API_KEY` from its environment.
 Rerun the installer:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
 ```
 
-The managed runtime is fetched again and checked out to the configured ref.
+The managed runtime is fetched again and checked out to the configured ref. By default that ref is the stable `v0.5.0` tag.
 
 ## Uninstalling a client integration
 
@@ -194,6 +194,31 @@ The bootstrap recognizes:
 | `JEV_MCP_CONFIG_HOME` | Override `~/.jev-mcp` |
 | `JEV_MCP_RUNTIME_DIR` | Override the managed runtime checkout |
 | `JEV_MCP_REPO_URL` | Override the Git repository URL |
-| `JEV_MCP_GIT_REF` | Override the fetched branch/tag/ref |
+| `JEV_MCP_GIT_REF` | Override the fetched branch/tag/ref; default is `v0.5.0` |
 
 These are primarily useful for testing, forks, and pinned deployments.
+
+
+## Stable vs development channel
+
+The stable bootstrap script and installed runtime are both pinned to the same release tag:
+
+```text
+v0.5.0
+```
+
+To intentionally follow the development branch:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | env JEV_MCP_GIT_REF=main bash -s -- codex
+```
+
+For PowerShell:
+
+```powershell
+$env:JEV_MCP_GIT_REF = "main"
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+```
+
+Development-channel users should expect behavior to change before the next
+tagged release.
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index c9f500c..9f22fac 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -17,13 +17,13 @@ client configuration.
 Codex on macOS/Linux:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
 ```
 
 Codex on Windows PowerShell:
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1))) -Target codex
 ```
 
 Other target IDs:
@@ -42,7 +42,7 @@ vscode
 Configure every detected user-level client on macOS/Linux:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash
 ```
 
 The installer creates:
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 028f0ba..8f25ba8 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -4,50 +4,69 @@ The repository is intentionally `private: true` in `package.json` to prevent
 accidental npm publication. Releases are GitHub source releases, not npm
 packages.
 
-## Automated path
+## Release model
 
-After Git and GitHub CLI are configured:
+Normal releases are now driven by the repository itself:
 
-```bash
-./scripts/publish-github.sh jev-mcp public
+1. prepare a release PR that updates `package.json`, `src/core.ts`,
+   `CHANGELOG.md`, and any stable installer defaults;
+2. merge only after CI passes;
+3. the post-CI auto-release workflow sees an untagged version on `main`;
+4. it creates the annotated `vX.Y.Z` tag and GitHub Release assets.
+
+No maintainer PAT or TypeSafe credential is required by the release workflow.
+
+The release contains:
+
+```text
+jev-mcp-X.Y.Z.zip
+jev-mcp-X.Y.Z.tar.gz
+SHA256SUMS.txt
 ```
 
-or on PowerShell:
+Release notes are extracted from the matching `CHANGELOG.md` section.
+
+## Manual fallback
+
+If automatic release is intentionally disabled:
 
-```powershell
-./scripts/publish-github.ps1 -RepoName jev-mcp -Visibility public
+```bash
+git checkout main
+git pull
+npm ci
+npm run check
+git tag -a v0.5.0 -m "jev-mcp v0.5.0"
+git push origin v0.5.0
 ```
 
-The script checks secrets and the build, creates/pushes the repository if
-needed, then pushes the version tag. The tag triggers the GitHub release
-workflow, which validates the project again and publishes source archives.
+The tag-triggered release workflow validates the tag against
+`package.json` and creates the same assets.
+
+## Stable installer channel
 
-## Manual release path
+The public bootstrap script is fetched from `main`, but the installed runtime
+must default to the latest stable version tag. For v0.5.0:
 
-1. Update `package.json` and `CHANGELOG.md`.
-2. Run `npm run check`.
-3. Commit the changes.
-4. Create an annotated tag, e.g. `git tag -a v0.4.1 -m "jev-mcp v0.4.1"`.
-5. Push `main` and the tag.
-6. The GitHub Actions release workflow creates the GitHub Release.
+```text
+JEV_MCP_GIT_REF default = v0.5.0
+```
 
-## Manual prerequisites only
+Development users can opt into:
+
+```text
+JEV_MCP_GIT_REF=main
+```
 
-Before the automated publishing script can act on your GitHub account, you must
-personally complete the account-bound steps:
+When cutting the next release, update the default stable ref in both
+`scripts/install.sh` and `scripts/install.ps1`.
 
-1. Install GitHub CLI (`gh`) if it is not already installed.
-2. Authenticate it with `gh auth login` (do not send access tokens to anyone).
-3. Configure your own Git author identity if needed:
-   `git config --global user.name ...` and `git config --global user.email ...`.
-4. Decide which GitHub owner/repository name should receive the project. Pass
-   `owner/jev-mcp` to the script if publishing under an organization.
+## Release checklist
 
-The script handles dependency installation, `package-lock.json`, staging,
-secret checks, tests/build, initial commit, repository creation, push, tag,
-repository topics/settings, security-scanning enablement where permitted, and
-release triggering.
+Before merging a version PR:
 
-After publication, adding a branch ruleset that requires CI before merging is
-recommended but intentionally left manual because organization policies and
-merge preferences vary.
+- version in `package.json` matches `src/core.ts`;
+- `CHANGELOG.md` contains `## X.Y.Z`;
+- Linux and Windows bootstrap smoke tests pass;
+- Node 20/22/24 checks pass;
+- stable installer default points at `vX.Y.Z`;
+- no credential or user-specific path appears in the diff.
diff --git a/package-lock.json b/package-lock.json
index 68c8d27..e7cfa83 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "jev-mcp",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "jev-mcp",
-      "version": "0.4.1",
+      "version": "0.5.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/server": "^2.0.0",
diff --git a/package.json b/package.json
index 8a7444d..2aa92cd 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "jev-mcp",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "private": true,
   "description": "Unofficial conservative MCP server exposing TypeSafe AI Jev as a secondary probabilistic decision signal.",
   "type": "module",
diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs
index e15595c..0f23652 100644
--- a/scripts/check-docs.mjs
+++ b/scripts/check-docs.mjs
@@ -63,6 +63,43 @@ if (!changelog.includes(`## ${pkg.version}`)) {
   errors.push(`CHANGELOG.md has no section for package version ${pkg.version}`);
 }
 
+const core = readFileSync(join(root, "src/core.ts"), "utf8");
+const coreVersion = core.match(/export const VERSION = "([^"]+)";/)?.[1];
+if (coreVersion !== pkg.version) {
+  errors.push(`src/core.ts VERSION (${coreVersion ?? "missing"}) does not match package.json (${pkg.version})`);
+}
+
+const lock = JSON.parse(readFileSync(join(root, "package-lock.json"), "utf8"));
+if (lock.version !== pkg.version || lock.packages?.[""]?.version !== pkg.version) {
+  errors.push(`package-lock.json version does not match package.json (${pkg.version})`);
+}
+
+const stableTag = `v${pkg.version}`;
+const unixInstaller = readFileSync(join(root, "scripts/install.sh"), "utf8");
+const windowsInstaller = readFileSync(join(root, "scripts/install.ps1"), "utf8");
+if (!unixInstaller.includes(`JEV_MCP_GIT_REF:-${stableTag}`)) {
+  errors.push(`scripts/install.sh default ref is not ${stableTag}`);
+}
+if (!windowsInstaller.includes(`"${stableTag}"`)) {
+  errors.push(`scripts/install.ps1 default ref is not ${stableTag}`);
+}
+
+const setupSh = readFileSync(join(root, "setup.sh"), "utf8");
+const setupPs = readFileSync(join(root, "setup.ps1"), "utf8");
+if (!setupSh.includes(`v${pkg.version} setup complete`)) {
+  errors.push(`setup.sh completion version does not match ${pkg.version}`);
+}
+if (!setupPs.includes(`v${pkg.version} setup complete`)) {
+  errors.push(`setup.ps1 completion version does not match ${pkg.version}`);
+}
+
+const readme = readFileSync(join(root, "README.md"), "utf8");
+const stableInstallUrl =
+  `https://raw.githubusercontent.com/Afloat16/jev-mcp/v${pkg.version}/scripts/install.sh`;
+if (!readme.includes(stableInstallUrl)) {
+  errors.push(`README.md does not point stable install at v${pkg.version}`);
+}
+
 for (const required of [
   "README.md",
   "README.zh-CN.md",
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 9fe5009..76e062f 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -35,7 +35,7 @@ $repoUrl = if ([string]::IsNullOrWhiteSpace($env:JEV_MCP_REPO_URL)) {
 }
 
 $gitRef = if ([string]::IsNullOrWhiteSpace($env:JEV_MCP_GIT_REF)) {
-  "main"
+  "v0.5.0"
 } else {
   $env:JEV_MCP_GIT_REF
 }
diff --git a/scripts/install.sh b/scripts/install.sh
index 35a6e2b..52624d2 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -22,7 +22,7 @@ fi
 config_home="${JEV_MCP_CONFIG_HOME:-$HOME/.jev-mcp}"
 runtime="${JEV_MCP_RUNTIME_DIR:-$config_home/runtime}"
 repo_url="${JEV_MCP_REPO_URL:-https://github.com/Afloat16/jev-mcp.git}"
-git_ref="${JEV_MCP_GIT_REF:-main}"
+git_ref="${JEV_MCP_GIT_REF:-v0.5.0}"
 
 mkdir -p "$config_home"
 chmod 700 "$config_home" 2>/dev/null || true
diff --git a/setup.ps1 b/setup.ps1
index e915c79..095bb4a 100644
--- a/setup.ps1
+++ b/setup.ps1
@@ -42,5 +42,5 @@ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 
 Write-Host ""
-Write-Host "jev-mcp v0.4.1 setup complete."
+Write-Host "jev-mcp v0.5.0 setup complete."
 Write-Host "Next: configure your MCP host using config.toml.snippet or the README example, then restart the host."
diff --git a/setup.sh b/setup.sh
index 9186316..6ead5f9 100644
--- a/setup.sh
+++ b/setup.sh
@@ -46,5 +46,5 @@ npm run check
 npm run doctor
 
 echo
-echo "jev-mcp v0.4.1 setup complete."
+echo "jev-mcp v0.5.0 setup complete."
 echo "Next: configure your MCP host using config.toml.snippet or the README example, then restart the host."
diff --git a/src/cli.ts b/src/cli.ts
index d5010b6..48df4ce 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -35,10 +35,10 @@ Targets:
 
 Recommended bootstrap:
   macOS/Linux:
-    curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+    curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
 
   Windows PowerShell:
-    & ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+    & ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1))) -Target codex
 
 After bootstrap, the local CLI lives under ~/.jev-mcp/runtime.
 `.trim());
diff --git a/src/core.ts b/src/core.ts
index 2652876..296873f 100644
--- a/src/core.ts
+++ b/src/core.ts
@@ -31,7 +31,7 @@ export type JevResponse = {
   };
 };
 
-export const VERSION = "0.4.1";
+export const VERSION = "0.5.0";
 
 export const JEV_ADVISORY = {
   authority: "secondary_advisory",