feat: add installer distribution docs

.gitignore

@@ -4,5 +4,6 @@
 /.openclaw-version
 .omx/
 .playwright-cli/
+site/public/ocvm/
 *.log
 .DS_Store

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- Replaced GitHub raw installer guidance with a static installer path that can be mirrored to OSS/CDN.
+- Added website documentation routes for installation, commands, configuration, and release sources.
+- Added GitHub and documentation navigation to the landing page.
 - Updated landing page and crate metadata for `https://ocvm.vercel.app`.
 - Clarified the site Install section around the pinned `v0.1.1` release.
 - Added a GitHub Actions site build gate for the Vercel app in `site/`.

README.md

@@ -198,12 +198,26 @@ Rollback does not delete unrelated installed versions.
 
 ## Install
 
-After a GitHub Release exists:
+After a GitHub Release exists, publish `install.sh` to a stable HTTPS path. The
+current site publishes the installer as a static asset, and the same layout can
+be mirrored to OSS or placed behind a CDN:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/PerfectPan/ocvm/v0.1.1/install.sh | sh
+curl -fsSL https://ocvm.vercel.app/ocvm/install.sh | sh
 ```
 
+For repeatable automation, pin the binary release with `OCVM_VERSION` while
+using the same installer script:
+
+```bash
+curl -fsSL https://ocvm.vercel.app/ocvm/install.sh | OCVM_VERSION=v0.1.1 sh
+```
+
+Maintainers set `OCVM_INSTALLER_BASE_URL` to the published OSS/CDN prefix during
+release preparation when mirroring the same layout outside Vercel. Future
+releases only need to update the stable installer script when the script itself
+changes or when its default pinned release changes.
+
 ## Docker E2E
 
 Run real npm OpenClaw install validation in Docker instead of on the host:
@@ -212,9 +226,11 @@ Run real npm OpenClaw install validation in Docker instead of on the host:
 ./scripts/e2e-docker.sh
 ```
 
-## Landing Page
+## Website and Docs
 
-The TanStack Start landing page is deployed at https://ocvm.vercel.app. Source lives in `site/` and is configured for Vercel deployments from that directory:
+The TanStack Start landing page and documentation site are deployed at
+https://ocvm.vercel.app. Source lives in `site/` and is configured for Vercel
+deployments from that directory:
 
 ```bash
 npm ci --prefix site

docs/plans/2026-05-17-installer-docs-design.md

@@ -0,0 +1,31 @@
+# Installer Distribution and Documentation Design
+
+## Goal
+
+Resolve GitHub issues #19 and #20 by making the installer distribution path resilient outside GitHub raw content and by giving new users a coherent landing and documentation experience.
+
+## Installer Distribution
+
+Common installer hosting should use one public object-storage path:
+
+```text
+https://<oss-or-cdn-domain>/ocvm/install.sh
+```
+
+The stable `install.sh` path is the recommended copy-paste command for most users. Repeatable automation should pin the binary release with `OCVM_VERSION=v0.1.1` while reusing the same script. This avoids uploading a new installer script for every release unless the script logic or default pinned release changes. The repository should not hard-code an unverified vendor bucket domain. Instead, docs and site copy should expose `OCVM_INSTALLER_BASE_URL` as the release-time value that maintainers set to their OSS or CDN prefix.
+
+The install script itself continues to resolve binaries from GitHub Releases unless `OCVM_REPO`, `GITHUB_API_URL`, or future release-source variables override that behavior. Issue #19 is specifically about avoiding GitHub raw content for downloading the script, not about changing release asset storage in this pass.
+
+## Documentation Site
+
+The existing `site/` app remains the single web project. It should add a `/docs` area that shares navigation, visual language, and install commands with the landing page. The docs area should be content-first and lightweight: installation, command reference, configuration, and release source pages are enough for the current CLI surface.
+
+Fumadocs is the target documentation framework. Because the current app is TanStack Start on Vite, integration should follow Fumadocs' Vite/TanStack path where practical. If package constraints make full Fumadocs UI integration risky in this pass, the repository should still adopt a docs route/content boundary that can be migrated cleanly to Fumadocs components later.
+
+## GitHub Stars
+
+The landing page should show GitHub star visibility without making rendering depend on a live GitHub API request. The first implementation can use a static repository stat value with a direct GitHub link and accessible label. A future enhancement can hydrate the value from GitHub with caching once a server data-loading convention is chosen.
+
+## Validation
+
+Run the Rust checks because this remains a publishable CLI repository. Run the site build because the web app changes user-facing behavior. Run a publish-safety scan before pushing. If dependency installation or networked package fetches fail, record the exact blocker and verify all offline-capable checks.

docs/plans/2026-05-17-installer-docs.md

@@ -0,0 +1,108 @@
+# Installer Distribution and Documentation Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Resolve GitHub issues #19 and #20 by replacing GitHub raw installer guidance with an OSS/CDN-ready distribution convention and adding a coherent documentation experience to the existing site.
+
+**Architecture:** Keep the Rust CLI at the repository root and the web experience in `site/`. Treat installer distribution as release documentation plus a reusable URL contract, and treat docs as a first-class route group in the existing TanStack Start app so landing and docs share copy, navigation, and styles.
+
+**Tech Stack:** Rust CLI, POSIX shell installer, TanStack Start, React, TypeScript, Vite, CSS, Fumadocs-compatible documentation structure.
+
+---
+
+### Task 1: Document the Installer Distribution Contract
+
+**Files:**
+- Modify: `README.md`
+- Modify: `docs/release.md`
+- Modify: `CHANGELOG.md`
+
+**Steps:**
+
+1. Add an OSS/CDN installer URL convention with one stable script path:
+   - `https://<oss-or-cdn-domain>/ocvm/install.sh`
+2. Document repeatable automation as `curl .../install.sh | OCVM_VERSION=v0.1.1 sh`.
+3. Keep GitHub raw as a maintainer fallback, not the primary user-facing install path.
+4. Document `OCVM_INSTALLER_BASE_URL` as the release-time prefix maintainers publish to object storage.
+4. Update changelog with user-facing installer guidance changes.
+5. Verify with `rg -n "raw.githubusercontent.com|OCVM_INSTALLER_BASE_URL|oss-or-cdn" README.md docs site install.sh CHANGELOG.md`.
+
+### Task 2: Add Shared Site Content for Install and Docs Navigation
+
+**Files:**
+- Create: `site/src/content.ts`
+- Modify: `site/src/routes/index.tsx`
+
+**Steps:**
+
+1. Extract current release, installer base URL, install command, repo URL, release URL, docs URL, and star label into `site/src/content.ts`.
+2. Use the shared install command on the landing page.
+3. Add a GitHub star link in the top navigation with a static accessible label.
+4. Point Docs navigation to `/docs` instead of a GitHub blob URL.
+5. Verify TypeScript imports by running `npm run build --prefix site`.
+
+### Task 3: Add Documentation Routes
+
+**Files:**
+- Create: `site/src/routes/docs.tsx`
+- Create: `site/src/routes/docs.installation.tsx`
+- Create: `site/src/routes/docs.commands.tsx`
+- Create: `site/src/routes/docs.configuration.tsx`
+- Create: `site/src/routes/docs.release-sources.tsx`
+
+**Steps:**
+
+1. Build `/docs` as an overview page with links to the four documentation pages.
+2. Add install docs covering the OSS/CDN convention and local bin setup.
+3. Add command docs matching the README command surface.
+4. Add configuration docs for `OCVM_HOME`, `OCVM_NPM_PACKAGE`, `OCVM_SOURCE`, and release manifest URL.
+5. Add release-source docs for npm and manifest source behavior.
+6. Keep docs content concise and current.
+7. Verify route generation/build with `npm run build --prefix site`.
+
+### Task 4: Unify Landing and Docs Styling
+
+**Files:**
+- Modify: `site/src/styles.css`
+
+**Steps:**
+
+1. Add shared top navigation styles that work for both landing and docs pages.
+2. Add docs layout styles with readable width, sidebar-like page index, and code blocks.
+3. Keep card radius at 8px or less and avoid nested cards.
+4. Check responsive rules for mobile and desktop.
+5. Verify visually with a local site server and browser screenshots when feasible.
+
+### Task 5: Verify Repository Gates
+
+**Commands:**
+
+```bash
+cargo fmt --check
+cargo clippy --all-targets -- -D warnings
+cargo test
+npm run build --prefix site
+cargo build --release
+cargo package --allow-dirty
+rg --hidden --no-ignore -n "private-token|secret|internal-domain.example|HOME_PATH_PLACEHOLDER" . --glob '!target/**' --glob '!.git/**' --glob '!.omx/**' --glob '!AGENTS.md' --glob '!CONTRIBUTING.md' --glob '!SECURITY.md'
+```
+
+If network or package-cache constraints block the site build, record the exact command and failure output, then run all checks that do not require new network access.
+
+### Task 6: Publish the Branch
+
+**Steps:**
+
+1. Inspect `git status --short --branch`.
+2. Review changed files for generated output, secrets, and machine paths.
+3. Commit with a concise conventional commit message ending with:
+
+```text
+Generated with Codex
+
+Co-Authored-By: Codex <noreply@openai.com>
+```
+
+4. Push the branch.
+5. Create or reuse a GitHub Pull Request.
+6. Include validation commands and remaining risks in the PR summary.

docs/release.md

@@ -25,16 +25,33 @@ The `Release` workflow builds platform binaries, packages archives, generates SH
 
 ## Install Script
 
-Users can install a specific release with:
+Publish the installer to object storage or a CDN after the GitHub Release is
+created. Use one stable script path for onboarding and pin the binary release
+with `OCVM_VERSION` when automation needs repeatable installs:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/PerfectPan/ocvm/v0.1.1/install.sh | sh
+export OCVM_INSTALLER_BASE_URL="https://ocvm.vercel.app/ocvm"
+
+# Stable installer path for the current release.
+curl -fsSL "$OCVM_INSTALLER_BASE_URL/install.sh" | sh
+
+# Repeatable install pinned to a specific binary release.
+curl -fsSL "$OCVM_INSTALLER_BASE_URL/install.sh" | OCVM_VERSION=v0.1.1 sh
 ```
 
 Override `OCVM_VERSION` to install a different release:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/PerfectPan/ocvm/v0.1.1/install.sh | OCVM_VERSION=latest sh
+curl -fsSL "$OCVM_INSTALLER_BASE_URL/install.sh" | OCVM_VERSION=latest sh
+```
+
+GitHub raw content can remain a maintainer fallback while testing release tags,
+but it should not be the primary user-facing install command.
+
+For an OSS bucket, mirror the same files and replace the prefix:
+
+```text
+ocvm/install.sh
 ```
 
 ## Docker E2E

scripts/check-release-prep.sh

@@ -24,6 +24,15 @@ expect_file_text() {
   }
 }
 
+expect_files_equal() {
+  left="$1"
+  right="$2"
+  cmp -s "$left" "$right" || {
+    echo "expected $left and $right to match" >&2
+    exit 1
+  }
+}
+
 expect_output "asset=ocvm-x86_64-unknown-linux-gnu.tar.gz" \
   env OCVM_INSTALL_DRY_RUN=1 OCVM_TEST_UNAME_S=Linux OCVM_TEST_UNAME_M=x86_64 ./install.sh
 
@@ -36,11 +45,14 @@ expect_output "asset=ocvm-aarch64-apple-darwin.tar.gz" \
 expect_output "api_url=https://api.github.com/repos/PerfectPan/ocvm/releases/tags/v0.1.1" \
   env OCVM_INSTALL_DRY_RUN=1 OCVM_VERSION=v0.1.1 OCVM_TEST_UNAME_S=Darwin OCVM_TEST_UNAME_M=arm64 ./install.sh
 
+./scripts/sync-site-installer.sh >/dev/null
+
 expect_file_text .github/workflows/release.yml "target: x86_64-unknown-linux-gnu"
 expect_file_text .github/workflows/release.yml "target: x86_64-apple-darwin"
 expect_file_text .github/workflows/release.yml "target: aarch64-apple-darwin"
 expect_file_text .github/workflows/release.yml "target: x86_64-pc-windows-msvc"
 expect_file_text .github/workflows/release.yml 'shasum -a 256 "${name}.tar.gz" > "${name}.tar.gz.sha256"'
 expect_file_text .github/workflows/release.yml '"$hash  $name.zip"'
+expect_files_equal install.sh site/public/ocvm/install.sh
 
 echo "release prep checks passed"

scripts/sync-site-installer.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+set -eu
+
+root="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
+install_script="$root/install.sh"
+site_installer_dir="$root/site/public/ocvm"
+
+mkdir -p "$site_installer_dir"
+cp "$install_script" "$site_installer_dir/install.sh"
+
+echo "synced site installer asset"