fix(release): verify npm latest tag and document @latest install (#1378)

* fix(release): verify npm latest tag and document @latest install

* fix(auto-updater): use @latest for global installs

.github/workflows/release.yml

@@ -79,6 +79,40 @@ jobs:
       - name: Publish to npm
         run: npm publish --access public --provenance
 
+      - name: Verify npm latest dist-tag
+        env:
+          EXPECTED_VERSION: ${{ needs.release-please.outputs.version }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${EXPECTED_VERSION}" ]; then
+            echo "release-please did not provide an expected version" >&2
+            exit 1
+          fi
+
+          for attempt in $(seq 1 30); do
+            published_version="$(npm view @gitlawb/openclaude version 2>/dev/null || true)"
+            latest_tag="$(npm view @gitlawb/openclaude dist-tags.latest 2>/dev/null || true)"
+            latest_version="$(npm view @gitlawb/openclaude@latest version 2>/dev/null || true)"
+
+            echo "Attempt ${attempt}: version=${published_version:-<empty>} latest=${latest_tag:-<empty>} @latest=${latest_version:-<empty>} expected=${EXPECTED_VERSION}"
+
+            if [ "$published_version" = "$EXPECTED_VERSION" ] && \
+               [ "$latest_tag" = "$EXPECTED_VERSION" ] && \
+               [ "$latest_version" = "$EXPECTED_VERSION" ]; then
+              echo "npm latest verified for @gitlawb/openclaude@${EXPECTED_VERSION}"
+              exit 0
+            fi
+
+            sleep 10
+          done
+
+          echo "npm latest dist-tag did not resolve to ${EXPECTED_VERSION}" >&2
+          echo "Observed package version: ${published_version:-<empty>}" >&2
+          echo "Observed dist-tags.latest: ${latest_tag:-<empty>}" >&2
+          echo "Observed @latest version: ${latest_version:-<empty>}" >&2
+          exit 1
+
       - name: Release summary
         run: |
           {

README.md

@@ -65,11 +65,19 @@ OpenClaude is also mirrored to GitLawb:
 ### Install
 
 ```bash
-npm install -g @gitlawb/openclaude
+npm install -g @gitlawb/openclaude@latest
 ```
 
 If the install later reports `ripgrep not found`, install ripgrep system-wide and confirm `rg --version` works in the same terminal before starting OpenClaude.
 
+**Verify / troubleshoot installed version:**
+
+```bash
+openclaude --version
+npm view @gitlawb/openclaude dist-tags
+npm install -g @gitlawb/openclaude@latest
+```
+
 ### Start
 
 ```bash

docs/advanced-setup.md

@@ -7,7 +7,7 @@ This guide is for users who want source builds, Bun workflows, provider profiles
 ### Option A: npm
 
 ```bash
-npm install -g @gitlawb/openclaude
+npm install -g @gitlawb/openclaude@latest
 ```
 
 ### Option B: From source with Bun

docs/quick-start-mac-linux.md

@@ -18,7 +18,7 @@ npm --version
 ## 2. Install OpenClaude
 
 ```bash
-npm install -g @gitlawb/openclaude
+npm install -g @gitlawb/openclaude@latest
 ```
 
 ## 3. Pick One Provider

docs/quick-start-windows.md

@@ -18,7 +18,7 @@ npm --version
 ## 2. Install OpenClaude
 
 ```powershell
-npm install -g @gitlawb/openclaude
+npm install -g @gitlawb/openclaude@latest
 ```
 
 ## 3. Pick One Provider

src/components/AutoUpdater.tsx

@@ -190,7 +190,7 @@ export function AutoUpdater({
       {(autoUpdaterResult?.status === 'install_failed' || autoUpdaterResult?.status === 'no_permissions') && <Text color="error" wrap="truncate">
           ✗ Auto-update failed &middot; Try <Text bold>openclaude doctor</Text> or{' '}
           <Text bold>
-            {hasLocalInstall ? `cd ~/.openclaude/local && npm update ${MACRO.PACKAGE_URL}` : `npm i -g ${MACRO.PACKAGE_URL}`}
+            {hasLocalInstall ? `cd ~/.openclaude/local && npm update ${MACRO.PACKAGE_URL}` : `npm i -g ${MACRO.PACKAGE_URL}@latest`}
           </Text>
         </Text>}
     </Box>;

src/utils/autoUpdater.ts

@@ -533,7 +533,7 @@ To fix this issue:
     // Use specific version if provided, otherwise use latest
     const packageSpec = specificVersion
       ? `${MACRO.PACKAGE_URL}@${specificVersion}`
-      : MACRO.PACKAGE_URL
+      : `${MACRO.PACKAGE_URL}@latest`
 
     // Run from home directory to avoid reading project-level .npmrc/.bunfig.toml
     // which could be maliciously crafted to redirect to an attacker's registry

vscode-extension/openclaude-vscode/README.md

@@ -28,7 +28,7 @@ A practical VS Code companion for OpenClaude with a project-aware **Control Cent
 ## Requirements
 
 - VS Code `1.95+`
-- `openclaude` available in your terminal PATH (`npm install -g @gitlawb/openclaude`)
+- `openclaude` available in your terminal PATH (`npm install -g @gitlawb/openclaude@latest`)
 
 ## Commands
 

vscode-extension/openclaude-vscode/src/extension.js

@@ -291,7 +291,7 @@ async function launchOpenClaude(options = {}) {
 
   if (!installed) {
     const action = await vscode.window.showErrorMessage(
-      `OpenClaude command not found: ${executable}. Install it with: npm install -g @gitlawb/openclaude`,
+      `OpenClaude command not found: ${executable}. Install it with: npm install -g @gitlawb/openclaude@latest`,
       'Open Setup Guide',
       'Open Repository',
     );

web/src/content.ts

@@ -1,4 +1,4 @@
-export const installCommand = 'npm install -g @gitlawb/openclaude'
+export const installCommand = 'npm install -g @gitlawb/openclaude@latest'
 
 export const features = [
   {