diff --git a/.github/actions/deploy-docs/action.yml b/.github/actions/deploy-docs/action.yml
new file mode 100644
index 0000000000..e03892e6b7
--- /dev/null
+++ b/.github/actions/deploy-docs/action.yml
@@ -0,0 +1,87 @@
+name: 'Build and deploy docs'
+description: >-
+  Build the VitePress docs site (which bundles install.sh / install.ps1 into
+  its public assets) and deploy it to a void.app project. Run on a Linux
+  runner after checkout. See rfcs/deploy-docs-on-release.md for which
+  workflow deploys to which project.
+
+inputs:
+  void-project:
+    description: 'void.app project to deploy to (e.g. viteplus, viteplus-main).'
+    required: true
+  void-token:
+    description: 'void.app deploy token (pass secrets.VOID_TOKEN).'
+    required: true
+  cache-ref:
+    description: >-
+      Ref-scoped segment of the Vite Task cache key: main, or pr-<number> for
+      PR previews. Non-main refs fall back to the main cache on restore.
+    required: false
+    default: 'main'
+  cache-sha:
+    description: 'Commit sha that scopes the primary cache key.'
+    required: false
+    default: ${{ github.sha }}
+  site-origin:
+    description: >-
+      Origin of this deploy when it is not production viteplus.dev
+      (e.g. https://main.viteplus.dev). When set, the docs build rewrites the
+      https://vite.plus installer URLs to this origin's install scripts.
+      Leave empty for production.
+    required: false
+    default: ''
+
+runs:
+  using: 'composite'
+  steps:
+    - uses: voidzero-dev/setup-vp@250f29ce396baf5e8f24498e17c0dfdebabc26eb # main
+      with:
+        cache: true
+        working-directory: docs
+        cache-dependency-path: docs/pnpm-lock.yaml
+
+    - name: Compute Vite Task cache keys
+      id: cache-keys
+      shell: bash
+      env:
+        CACHE_REF: ${{ inputs.cache-ref }}
+        CACHE_SHA: ${{ inputs.cache-sha }}
+      run: |
+        prefix="vite-task-docs-${RUNNER_OS}-${RUNNER_ARCH}"
+        {
+          echo "key=${prefix}-${CACHE_REF}-${CACHE_SHA}"
+          echo 'restore-keys<<EOF'
+          echo "${prefix}-${CACHE_REF}-"
+          if [ "$CACHE_REF" != 'main' ]; then
+            echo "${prefix}-main-"
+          fi
+          echo 'EOF'
+        } >> "$GITHUB_OUTPUT"
+
+    - name: Restore docs Vite Task cache
+      id: vite-task-cache
+      uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+      with:
+        path: docs/node_modules/.vite/task-cache
+        key: ${{ steps.cache-keys.outputs.key }}
+        # Prefer this ref's newest cache; Vite Task fingerprints decide reuse.
+        restore-keys: ${{ steps.cache-keys.outputs.restore-keys }}
+
+    - run: vp run build
+      shell: bash
+      working-directory: docs
+      env:
+        DOCS_SITE_ORIGIN: ${{ inputs.site-origin }}
+
+    - name: Save docs Vite Task cache
+      if: success() && steps.vite-task-cache.outputs.cache-hit != 'true'
+      uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+      with:
+        path: docs/node_modules/.vite/task-cache
+        key: ${{ steps.vite-task-cache.outputs.cache-primary-key }}
+
+    - run: vpx void deploy --dir docs/.vitepress/dist
+      shell: bash
+      env:
+        VOID_PROJECT: ${{ inputs.void-project }}
+        VOID_TOKEN: ${{ inputs.void-token }}
diff --git a/.github/workflows/deploy-docs-main.yml b/.github/workflows/deploy-docs-main.yml
new file mode 100644
index 0000000000..9b7a309d28
--- /dev/null
+++ b/.github/workflows/deploy-docs-main.yml
@@ -0,0 +1,40 @@
+name: Deploy Docs Main Preview
+
+permissions: {}
+
+# Deploys the docs at the head of main to main.viteplus.dev (the viteplus-main
+# void.app project) so developers can preview unreleased docs. Production
+# viteplus.dev deploys from release.yml instead.
+# See rfcs/deploy-docs-on-release.md.
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'packages/cli/install.sh'
+      - 'packages/cli/install.ps1'
+      - '.github/workflows/deploy-docs-main.yml'
+      - '.github/actions/deploy-docs/**'
+
+concurrency:
+  group: deploy-docs-main
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  deploy:
+    if: github.repository == 'voidzero-dev/vite-plus'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2
+
+      - uses: ./.github/actions/deploy-docs
+        with:
+          void-project: viteplus-main
+          void-token: ${{ secrets.VOID_TOKEN }}
+          site-origin: https://main.viteplus.dev
diff --git a/.github/workflows/deploy-docs-preview.yml b/.github/workflows/deploy-docs-preview.yml
index 2267f3192b..2579e08698 100644
--- a/.github/workflows/deploy-docs-preview.yml
+++ b/.github/workflows/deploy-docs-preview.yml
@@ -9,6 +9,7 @@ on:
       - 'packages/cli/install.sh'
       - 'packages/cli/install.ps1'
       - '.github/workflows/deploy-docs-preview.yml'
+      - '.github/actions/deploy-docs/**'
 
 concurrency:
   group: deploy-docs-preview-${{ github.event.pull_request.number }}
@@ -28,41 +29,17 @@ jobs:
       contents: read
       pull-requests: write
     env:
-      VOID_PROJECT: viteplus-staging
       PREVIEW_URL: https://viteplus-staging.void.app/
     steps:
       - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2
 
-      - uses: voidzero-dev/setup-vp@250f29ce396baf5e8f24498e17c0dfdebabc26eb # main
+      - uses: ./.github/actions/deploy-docs
         with:
-          cache: true
-          working-directory: docs
-          cache-dependency-path: docs/pnpm-lock.yaml
-
-      - name: Restore docs Vite Task cache
-        id: vite-task-cache
-        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: docs/node_modules/.vite/task-cache
-          key: vite-task-docs-${{ runner.os }}-${{ runner.arch }}-pr-${{ github.event.pull_request.number }}-${{ github.event.pull_request.head.sha }}
-          # Prefer this PR's newest cache, then fall back to main for new PRs.
-          restore-keys: |
-            vite-task-docs-${{ runner.os }}-${{ runner.arch }}-pr-${{ github.event.pull_request.number }}-
-            vite-task-docs-${{ runner.os }}-${{ runner.arch }}-main-
-
-      - run: vp run build
-        working-directory: docs
-
-      - name: Save docs Vite Task cache
-        if: success() && steps.vite-task-cache.outputs.cache-hit != 'true'
-        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: docs/node_modules/.vite/task-cache
-          key: ${{ steps.vite-task-cache.outputs.cache-primary-key }}
-
-      - run: vpx void deploy --dir docs/.vitepress/dist
-        env:
-          VOID_TOKEN: ${{ secrets.VOID_TOKEN }}
+          void-project: viteplus-staging
+          void-token: ${{ secrets.VOID_TOKEN }}
+          cache-ref: pr-${{ github.event.pull_request.number }}
+          cache-sha: ${{ github.event.pull_request.head.sha }}
+          site-origin: https://viteplus-staging.void.app
 
       - name: Comment on PR
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index 6d365252cf..c205ab9e60 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -2,16 +2,18 @@ name: Deploy Docs
 
 permissions: {}
 
+# Deploys production viteplus.dev, which also serves install.sh / install.ps1
+# behind https://vite.plus. Runs from release.yml after a stable release is
+# published, or manually here for urgent updates. Pushes to main deploy to
+# main.viteplus.dev via deploy-docs-main.yml instead.
+# See rfcs/deploy-docs-on-release.md.
 on:
-  push:
-    branches: [main]
-    paths:
-      - 'docs/**'
-      - 'packages/cli/install.sh'
-      - 'packages/cli/install.ps1'
-      - '.github/workflows/deploy-docs.yml'
   workflow_dispatch:
 
+# Shared with the deploy-docs job in release.yml so production deploys
+# serialize across both entry paths. GitHub keeps only the newest pending run
+# in the group (a queued deploy replaces a pending one), so production
+# converges to the newest queued content; the running deploy always completes.
 concurrency:
   group: deploy-docs
   cancel-in-progress: false
@@ -26,37 +28,10 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-    env:
-      VOID_PROJECT: viteplus
     steps:
       - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2
 
-      - uses: voidzero-dev/setup-vp@250f29ce396baf5e8f24498e17c0dfdebabc26eb # main
+      - uses: ./.github/actions/deploy-docs
         with:
-          cache: true
-          working-directory: docs
-          cache-dependency-path: docs/pnpm-lock.yaml
-
-      - name: Restore docs Vite Task cache
-        id: vite-task-cache
-        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: docs/node_modules/.vite/task-cache
-          key: vite-task-docs-${{ runner.os }}-${{ runner.arch }}-main-${{ github.sha }}
-          # Restore the latest main cache; Vite Task fingerprints decide reuse.
-          restore-keys: |
-            vite-task-docs-${{ runner.os }}-${{ runner.arch }}-main-
-
-      - run: vp run build
-        working-directory: docs
-
-      - name: Save docs Vite Task cache
-        if: success() && steps.vite-task-cache.outputs.cache-hit != 'true'
-        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: docs/node_modules/.vite/task-cache
-          key: ${{ steps.vite-task-cache.outputs.cache-primary-key }}
-
-      - run: vpx void deploy --dir docs/.vitepress/dist
-        env:
-          VOID_TOKEN: ${{ secrets.VOID_TOKEN }}
+          void-project: viteplus
+          void-token: ${{ secrets.VOID_TOKEN }}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 62581f316c..207d308550 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -213,6 +213,34 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: gh release edit "v${VERSION}" --draft=false --repo "${{ github.repository }}"
 
+  # Deploy viteplus.dev from the release commit after the npm packages and the
+  # GitHub release are published, so the site and the install scripts always
+  # match the released vp. Skipped for prereleases: production docs must keep
+  # describing the latest stable release. See rfcs/deploy-docs-on-release.md.
+  deploy-docs:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    needs: [check, Release]
+    if: >-
+      needs.check.outputs.version_changed == 'true' &&
+      !contains(needs.check.outputs.version, '-')
+    # Shared with deploy-docs.yml so production deploys serialize across both
+    # entry paths. Only the newest pending run survives in the group; if this
+    # job's pending run is replaced by a manual dispatch, the canceled job
+    # holds back discord-notify and the deploy must be re-run.
+    concurrency:
+      group: deploy-docs
+      cancel-in-progress: false
+    permissions:
+      contents: read
+    steps:
+      - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2
+
+      - uses: ./.github/actions/deploy-docs
+        with:
+          void-project: viteplus
+          void-token: ${{ secrets.VOID_TOKEN }}
+
   # Build and push the official toolchain Docker image to GHCR after the npm
   # release is published (the image installs vp from npm, so the version must
   # exist first). See docker/Dockerfile and docs/guide/docker.md.
@@ -266,15 +294,22 @@ jobs:
             VP_VERSION=${{ env.VERSION }}
           provenance: false
 
-  # Announce the release on Discord last, after the Docker images are published,
-  # so the message can include the GHCR image. Runs after the npm release
-  # (Release) and the images (publish-docker).
+  # Announce the release on Discord last, after the Docker images and the docs
+  # are published, so the message never points at a missing image or a site
+  # that still shows the previous release.
   discord-notify:
     name: Notify Discord
     runs-on: ubuntu-latest
     # publish-docker already needs Release, so depending on it orders this last.
-    needs: [check, publish-docker]
-    if: needs.check.outputs.version_changed == 'true'
+    # deploy-docs is skipped for prereleases; gate on its result explicitly so
+    # prerelease announcements still go out, while a failed docs deploy on a
+    # stable release holds the announcement back.
+    needs: [check, publish-docker, deploy-docs]
+    if: >-
+      !cancelled() &&
+      needs.check.outputs.version_changed == 'true' &&
+      needs.publish-docker.result == 'success' &&
+      (needs.deploy-docs.result == 'success' || needs.deploy-docs.result == 'skipped')
     env:
       VERSION: ${{ needs.check.outputs.version }}
       IMAGE: ghcr.io/voidzero-dev/vite-plus
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 413fc85b26..293673f43f 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -7,6 +7,26 @@ import { groupIconMdPlugin, groupIconVitePlugin } from 'vitepress-plugin-group-i
 import llmstxt from 'vitepress-plugin-llms';
 import { withMermaid } from 'vitepress-plugin-mermaid';
 
+// Non-production deploys (the main preview, PR staging) serve their own
+// copies of the install scripts and llms dumps, so the https://vite.plus
+// installer shortcuts and absolute site URLs must point at the deploy's
+// origin instead of production. The deploy workflows set DOCS_SITE_ORIGIN via
+// the deploy-docs composite action; markdown content is rewritten through
+// markdown-it below, and Vue components read the __DOCS_*__ define constants.
+const siteOrigin = process.env.DOCS_SITE_ORIGIN;
+const docsOrigin = siteOrigin || 'https://viteplus.dev';
+const installShUrl = siteOrigin ? `${siteOrigin}/install.sh` : 'https://vite.plus';
+const installPs1Url = siteOrigin ? `${siteOrigin}/install.ps1` : 'https://vite.plus/ps1';
+
+function rewriteInstallUrls(text: string): string {
+  if (!siteOrigin) {
+    return text;
+  }
+  return text
+    .replaceAll('https://vite.plus/ps1', installPs1Url)
+    .replaceAll('https://vite.plus', installShUrl);
+}
+
 const taskRunnerGuideItems = [
   {
     text: 'Run',
@@ -113,6 +133,11 @@ export default extendConfig(
         ['meta', { name: 'twitter:site', content: '@voidzerodev' }],
       ],
       vite: {
+        define: {
+          __DOCS_ORIGIN__: JSON.stringify(docsOrigin),
+          __DOCS_INSTALL_SH_URL__: JSON.stringify(installShUrl),
+          __DOCS_INSTALL_PS1_URL__: JSON.stringify(installPs1Url),
+        },
         optimizeDeps: {
           include: ['mermaid > @braintree/sanitize-url'],
         },
@@ -258,6 +283,31 @@ export default extendConfig(
       markdown: {
         config(md) {
           md.use(groupIconMdPlugin);
+          if (siteOrigin) {
+            md.core.ruler.push('rewrite-install-urls', (state) => {
+              const walk = (tokens: typeof state.tokens) => {
+                for (const token of tokens) {
+                  if (
+                    token.type === 'fence' ||
+                    token.type === 'code_inline' ||
+                    token.type === 'text'
+                  ) {
+                    token.content = rewriteInstallUrls(token.content);
+                  }
+                  if (token.type === 'link_open') {
+                    const href = token.attrGet('href');
+                    if (href) {
+                      token.attrSet('href', rewriteInstallUrls(href));
+                    }
+                  }
+                  if (token.children) {
+                    walk(token.children);
+                  }
+                }
+              };
+              walk(state.tokens);
+            });
+          }
         },
       },
     }),
diff --git a/docs/.vitepress/env.d.ts b/docs/.vitepress/env.d.ts
index adcc6abf4e..23ce8f7581 100644
--- a/docs/.vitepress/env.d.ts
+++ b/docs/.vitepress/env.d.ts
@@ -1,3 +1,13 @@
+// Build-time constants injected via vite.define in config.mts. They point at
+// the current deploy's origin (production, main preview, or PR staging). The
+// dunder names follow the Vite convention for compile-time replaced globals.
+// oxlint-disable-next-line no-underscore-dangle
+declare const __DOCS_ORIGIN__: string;
+// oxlint-disable-next-line no-underscore-dangle
+declare const __DOCS_INSTALL_SH_URL__: string;
+// oxlint-disable-next-line no-underscore-dangle
+declare const __DOCS_INSTALL_PS1_URL__: string;
+
 // Vue SFC module declaration
 declare module '*.vue' {
   import type { DefineComponent } from 'vue';
diff --git a/docs/.vitepress/theme/components/CopyPrompt.vue b/docs/.vitepress/theme/components/CopyPrompt.vue
index 1520b16379..1b9de196d7 100644
--- a/docs/.vitepress/theme/components/CopyPrompt.vue
+++ b/docs/.vitepress/theme/components/CopyPrompt.vue
@@ -7,11 +7,11 @@ import { computed, onBeforeUnmount, ref, useId } from 'vue';
 // live llms-full.txt docs dump.
 const DEFAULT_PROMPT = `I want to use Vite+ in my project. Vite+ is the unified toolchain for the web behind the \`vp\` CLI — one tool combining Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task, plus runtime and package-manager management.
 
-First, read https://viteplus.dev/llms-full.txt to learn Vite+'s commands and configuration.
+First, read ${__DOCS_ORIGIN__}/llms-full.txt to learn Vite+'s commands and configuration.
 
 Install the \`vp\` CLI if it's not already on the system:
-- macOS / Linux: curl -fsSL https://vite.plus | bash
-- Windows (PowerShell): irm https://vite.plus/ps1 | iex
+- macOS / Linux: curl -fsSL ${__DOCS_INSTALL_SH_URL__} | bash
+- Windows (PowerShell): irm ${__DOCS_INSTALL_PS1_URL__} | iex
 
 Then open a new terminal and run \`vp help\`. To scaffold a new project run \`vp create\`; to move an existing Vite project onto Vite+ run \`vp migrate\`.
 
@@ -19,17 +19,22 @@ Day-to-day commands: \`vp install\` (dependencies), \`vp dev\` (dev server), \`v
 
 Help me get set up and explain anything I should know.`;
 
+// DEFAULT_PROMPT interpolates the __DOCS_*__ define constants, so it is not a
+// static literal and cannot be a withDefaults() default (defineProps is
+// hoisted out of setup). Resolve the fallback in promptText instead.
 const props = withDefaults(
   defineProps<{
     prompt?: string;
     label?: string;
   }>(),
   {
-    prompt: DEFAULT_PROMPT,
+    prompt: '',
     label: 'View Prompt',
   },
 );
 
+const promptText = computed(() => props.prompt || DEFAULT_PROMPT);
+
 const titleId = useId();
 const dialogEl = ref<HTMLDialogElement | null>(null);
 const state = ref<'idle' | 'copied' | 'error'>('idle');
@@ -71,7 +76,7 @@ const blurPointerTarget = (event: MouseEvent) => {
 const copyPrompt = async (event: MouseEvent) => {
   blurPointerTarget(event);
   try {
-    await navigator.clipboard.writeText(props.prompt);
+    await navigator.clipboard.writeText(promptText.value);
     flash('copied');
   } catch {
     flash('error');
@@ -132,7 +137,7 @@ onBeforeUnmount(() => {
         </header>
         <pre
           class="m-0 overflow-auto px-5 pb-4 font-mono text-sm leading-relaxed break-words whitespace-pre-wrap"
-          >{{ prompt }}</pre>
+          >{{ promptText }}</pre>
         <footer class="flex justify-end border-t border-stroke px-5 py-3 dark:border-nickel">
           <button type="button" class="button" @click="copyPrompt">
             <Icon :icon="copyIcon" class="size-4" aria-hidden="true" />
diff --git a/docs/.vitepress/theme/components/home/InstallCommand.vue b/docs/.vitepress/theme/components/home/InstallCommand.vue
index 9773e94115..fbdfa00aba 100644
--- a/docs/.vitepress/theme/components/home/InstallCommand.vue
+++ b/docs/.vitepress/theme/components/home/InstallCommand.vue
@@ -12,12 +12,12 @@ const commandCards: CommandCard[] = [
   {
     id: 'unix',
     label: 'macOS / Linux',
-    command: 'curl -fsSL https://vite.plus | bash',
+    command: `curl -fsSL ${__DOCS_INSTALL_SH_URL__} | bash`,
   },
   {
     id: 'windows',
     label: 'Windows (PowerShell)',
-    command: 'irm https://vite.plus/ps1 | iex',
+    command: `irm ${__DOCS_INSTALL_PS1_URL__} | iex`,
   },
 ];
 
diff --git a/docs/vite.config.ts b/docs/vite.config.ts
index 217728eb50..6cbc6a0c37 100644
--- a/docs/vite.config.ts
+++ b/docs/vite.config.ts
@@ -3,6 +3,9 @@ export default {
     tasks: {
       'build:site': {
         command: 'vitepress build',
+        // The install-URL rewrite in .vitepress/config.mts depends on this
+        // variable, so different deploy targets must not share cached output.
+        env: ['DOCS_SITE_ORIGIN'],
         input: [
           { auto: true },
           '!.vitepress/.temp/**',
diff --git a/rfcs/deploy-docs-on-release.md b/rfcs/deploy-docs-on-release.md
new file mode 100644
index 0000000000..5e21b7bf68
--- /dev/null
+++ b/rfcs/deploy-docs-on-release.md
@@ -0,0 +1,321 @@
+# RFC: Deploy docs on release
+
+- Motivating example: [#2346](https://github.com/voidzero-dev/vite-plus/pull/2346) (XDG directory layout, rewrites `install.sh` / `install.ps1`)
+
+## Summary
+
+Stop deploying viteplus.dev on every push to `main`. Deploy it from the release
+workflow after the npm packages and the GitHub release are published, and keep
+`workflow_dispatch` for manual deploys. The site and the install scripts then
+always describe the latest released `vp`.
+
+Pushes to `main` keep an automatic deploy, but to a dedicated preview project
+at `https://main.viteplus.dev` (a CNAME to `viteplus-main.void.app`), so
+developers can read the latest docs on `main` before the next release.
+
+## Current behavior
+
+`deploy-docs.yml` runs on every push to `main` that touches `docs/**`,
+`packages/cli/install.sh`, `packages/cli/install.ps1`, or the workflow file. It
+builds the VitePress site and deploys it to the `viteplus` void.app project.
+
+The docs build copies the install scripts into the site
+(`docs/package.json` `build` script copies them into `docs/public/`).
+`https://vite.plus` redirects to `https://viteplus.dev/install.sh`, and
+`https://vite.plus/ps1` to `install.ps1`. The docs deploy is therefore also the
+production channel for the installer.
+
+The release pipeline is separate. Merging a release PR bumps
+`packages/cli/package.json`; `release.yml` verifies the version changed, builds,
+waits for manual approval in the `release` environment, then publishes the npm
+packages, the GitHub release, and the Docker image.
+
+This creates two failure modes:
+
+1. **Feature docs go live before the release exists.** A PR that adds code and
+   documents it deploys the docs at merge time. Users read about commands and
+   flags the released `vp` does not have. The gap between merge and release can
+   be days, since releases need a version bump and manual approval.
+2. **Install-script changes go live before the binaries that match them.**
+   [#2346](https://github.com/voidzero-dev/vite-plus/pull/2346) is the concrete
+   case: merging it would serve an `install.sh` that installs into the split
+   XDG layout, while `vp` from the latest release still resolves the legacy
+   `~/.vite-plus` layout. Fresh installs break until the next release ships.
+
+## Proposal
+
+Four parts:
+
+1. Extract the docs build and deploy steps into a
+   `.github/actions/deploy-docs` composite action, the repo convention for
+   shared step sequences (see `.github/actions/clone`, `build-windows-cli`).
+2. Reduce `deploy-docs.yml` to a manual (`workflow_dispatch`) production
+   deploy that runs the composite.
+3. Add a `deploy-docs` job to `release.yml` that runs the composite after the
+   release is published.
+4. Add `deploy-docs-main.yml`, which takes over the push trigger and deploys
+   `main` to the `viteplus-main` preview project.
+5. Switch `deploy-docs-preview.yml` to the composite; its trigger, staging
+   target, and PR comment step stay as they are.
+
+### `.github/actions/deploy-docs`
+
+The composite action holds the steps shared by every docs deploy: `setup-vp`,
+the Vite Task cache restore/save, `vp run build`, and `vpx void deploy`. Its
+inputs:
+
+- `void-project`: the deploy target.
+- `void-token`: composite actions cannot read secrets, so the caller passes
+  `secrets.VOID_TOKEN`.
+- `cache-ref` / `cache-sha` (optional, default `main` / `github.sha`): scope
+  the Vite Task cache key. PR previews pass `pr-<number>` and the head sha,
+  which reproduces their current per-PR keys with a fallback to the `main`
+  cache.
+
+Callers check out the repo first, then run the action.
+
+### `deploy-docs.yml`
+
+Remove the `push` trigger; keep `workflow_dispatch` only. The build and
+deploy steps move to the composite:
+
+```yaml
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    if: github.repository == 'voidzero-dev/vite-plus'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: taiki-e/checkout-action@... # v1.4.2
+
+      - uses: ./.github/actions/deploy-docs
+        with:
+          void-project: viteplus
+          void-token: ${{ secrets.VOID_TOKEN }}
+```
+
+### `release.yml`
+
+Add one job:
+
+```yaml
+deploy-docs:
+  name: Deploy docs
+  runs-on: ubuntu-latest
+  needs: [check, Release]
+  if: >-
+    needs.check.outputs.version_changed == 'true' &&
+    !contains(needs.check.outputs.version, '-')
+  concurrency:
+    group: deploy-docs
+    cancel-in-progress: false
+  permissions:
+    contents: read
+  steps:
+    - uses: taiki-e/checkout-action@... # v1.4.2
+
+    - uses: ./.github/actions/deploy-docs
+      with:
+        void-project: viteplus
+        void-token: ${{ secrets.VOID_TOKEN }}
+```
+
+- The job checks out `github.sha`, which in the release run is the release
+  commit. The deployed site matches the released version.
+- The job-level `deploy-docs` concurrency group is shared with
+  `deploy-docs.yml`, so production deploys serialize across both entry paths.
+- GitHub keeps one pending run per concurrency group: a newer queued deploy
+  replaces a pending one, while the running deploy always completes. So
+  production converges to the newest queued deploy. If a release's pending
+  deploy is the one replaced, the canceled job shows in the release run and
+  holds back `discord-notify`; re-run it if the replacing deploy carried
+  older content.
+- `needs: [check, Release]` runs the deploy once npm and the GitHub release are
+  out, in parallel with `publish-docker`. Docs do not depend on the image.
+- The `!contains(version, '-')` guard skips prereleases. An alpha publish must
+  not overwrite the production site with docs for unreleased behavior.
+- `discord-notify` adds `deploy-docs` to its `needs` and gates on
+  `result == 'success' || result == 'skipped'`, so a stable release announces
+  only after the site is updated, while prereleases (where `deploy-docs` is
+  skipped) still announce.
+- A docs-deploy failure does not undo the release; it holds back the Discord
+  announcement. Re-run the job or dispatch the workflow manually.
+
+### `deploy-docs-main.yml`: standing preview of `main`
+
+A new workflow takes over the push trigger that `deploy-docs.yml` loses. It
+runs the same composite and deploys to a dedicated `viteplus-main` void.app
+project instead of production:
+
+```yaml
+name: Deploy Docs Main Preview
+
+permissions: {}
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'packages/cli/install.sh'
+      - 'packages/cli/install.ps1'
+      - '.github/workflows/deploy-docs-main.yml'
+      - '.github/actions/deploy-docs/**'
+
+concurrency:
+  group: deploy-docs-main
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    if: github.repository == 'voidzero-dev/vite-plus'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: taiki-e/checkout-action@... # v1.4.2
+
+      - uses: ./.github/actions/deploy-docs
+        with:
+          void-project: viteplus-main
+          void-token: ${{ secrets.VOID_TOKEN }}
+```
+
+- `https://main.viteplus.dev` always shows the docs at the head of `main`,
+  including unreleased features. Developers get a stable link to share,
+  without a release or a manual dispatch.
+- A dedicated project, not the shared `viteplus-staging` one: PR previews
+  deploy there and would overwrite the `main` preview on every PR push.
+- `cancel-in-progress: true`: only the newest `main` deploy matters for a
+  preview. Production keeps `false`.
+- The workflow can keep the `vite-task-docs-*-main-*` cache keys that
+  `deploy-docs.yml` uses today, since both build `main`; the release-run
+  deploy restores from the same key family.
+- Setup before the workflow lands: create the `viteplus-main` project on the
+  void platform (the deploy uses the same `VOID_TOKEN` secret), add the DNS
+  CNAME `main.viteplus.dev` -> `viteplus-main.void.app`, and attach the
+  custom domain to the project.
+
+`deploy-docs-preview.yml` keeps its trigger, its `viteplus-staging.void.app`
+target, and its PR comment step, and now runs the same composite. Per-PR
+staging deploys remain the place to review docs changes before merge.
+
+### Origin-aware install URLs in the docs
+
+The docs hardcode the production installer shortcuts (`https://vite.plus`,
+`https://vite.plus/ps1`) in markdown code blocks and in the homepage Vue
+components. A preview deploy must point them at its own install scripts
+instead (for example `https://main.viteplus.dev/install.sh`), or readers of
+unreleased install docs run the production installer.
+
+The composite action passes its `site-origin` input to the docs build as
+`DOCS_SITE_ORIGIN`. When the variable is set:
+
+- A markdown-it rule in `.vitepress/config.mts` rewrites the install URLs in
+  fenced code, inline code, text, and link hrefs. Other `viteplus.dev`
+  subdomains (`setup.`, `registry-bridge.`) stay untouched.
+- The Vue components (homepage install command, AI copy prompt) read
+  `__DOCS_*__` define constants computed from the same origin. The AI prompt
+  also points at the deploy's own `llms-full.txt`.
+- The `build:site` run task lists `DOCS_SITE_ORIGIN` in `env`, so each deploy
+  target keeps its own Vite Task cache entry.
+
+Production builds leave the content untouched: the variable is unset there.
+Known gap: the llms dumps (`llms.txt`, `llms-full.txt`, per-page `.md`) copy
+raw markdown, so on previews they keep the production install URLs.
+
+### Manual deploys
+
+`workflow_dispatch` covers urgent updates outside the release cycle:
+
+- Main carries no unreleased docs since the last release commit: merge the fix
+  to `main`, dispatch Deploy Docs on `main`.
+- Main already carries unreleased docs: cut a branch from the release tag,
+  cherry-pick the fix, dispatch Deploy Docs on that branch. `workflow_dispatch`
+  accepts any branch or tag as the ref.
+
+A dispatch on `main` publishes everything on `main`, including unreleased docs
+if present. The operator has to check for that; the release-tag branch is the
+safe path.
+
+### No chicken-and-egg on the installer
+
+The docs build in the release run installs `vp` through `setup-vp`, which
+fetches the install script currently deployed on viteplus.dev. The run builds
+the site with the previous script, then the deploy replaces it. Fresh installs
+after the deploy get the new script together with the new binaries.
+
+## Why a job in the release run and not another trigger
+
+- `on: release: types: [published]` does not fire. `release.yml` publishes the
+  release with the default `GITHUB_TOKEN` (`gh release edit --draft=false`),
+  and events created with `GITHUB_TOKEN` do not start workflow runs. A PAT or
+  GitHub App token would work around this at the cost of another credential.
+- `workflow_run` on Release completion runs at the head of the default branch,
+  not at the release commit. Docs merged after the release commit would deploy
+  with it, which reintroduces problem 1.
+- `gh workflow run` at the end of the Release job works (`workflow_dispatch`
+  is exempt from the `GITHUB_TOKEN` restriction) but needs `actions: write`
+  and detaches the deploy from the release run in the Actions UI. A job in
+  the release run keeps the deploy visible and gated inside it.
+
+## Behavior changes
+
+| Event                                                | Before                      | After                                           |
+| ---------------------------------------------------- | --------------------------- | ----------------------------------------------- |
+| Docs change merges to `main`                         | Production deploy           | Preview deploy to `main.viteplus.dev`           |
+| `install.sh` / `install.ps1` change merges to `main` | Production deploy           | Preview deploy to `main.viteplus.dev`           |
+| Stable release published                             | No docs deploy              | Production deploy from the release commit       |
+| Prerelease published                                 | No docs deploy              | No docs deploy (`main` preview already current) |
+| Manual dispatch                                      | Redundant with push deploys | The escape hatch for urgent production updates  |
+
+## Drawbacks
+
+- Docs-only fixes (typos, clarifications) reach production with the next
+  release unless someone dispatches a deploy. Today they go live within
+  minutes of merge. They do reach `viteplus-main` within minutes.
+- The production site lags `main` by design. Contributors who expect merged
+  docs on viteplus.dev must link to `main.viteplus.dev` until the next
+  release.
+- One more job in `release.yml`, and the release run gains the docs build time
+  (a few minutes, in parallel with the Docker publish).
+- Two sites can index in search engines. The preview project should send
+  `noindex` (or the theme should emit it when the site URL is not
+  viteplus.dev) so `main.viteplus.dev` does not compete with production.
+
+## Alternatives considered
+
+- **Gate only the install scripts, keep push deploys for `docs/**`.** Fixes
+  problem 2 but not problem 1, and lets `docs/guide/install.md` drift from the
+  script it documents. Two freshness channels on one site.
+- **Versioned docs.** Publish `main` but hide unreleased sections until their
+  release. Needs authoring conventions and theme/tooling support; out of scope.
+- **A reusable workflow (`workflow_call`) called from `release.yml`, instead
+  of a composite action.** `reusable-release-build.yml` sets a precedent, but
+  it reuses a whole job matrix; the docs deploy reuses a step sequence inside
+  jobs with different triggers, gates, and concurrency, which is what the
+  `.github/actions` composites are for. `workflow_call` also carries
+  subtleties: the called workflow inherits the caller's `github` context and
+  event, its workflow-level concurrency has no effect, and secrets must be
+  declared and forwarded. The composite avoids all three and also serves
+  `deploy-docs-preview.yml`.
+- **One workflow file for production and the `main` preview, with the project
+  chosen by trigger.** Selecting `VOID_PROJECT` from `github.event_name` is
+  implicit and fragile, and `release.yml` still needs its own release-gated
+  job. Thin wrappers with explicit projects read clearer.
+- **Deploy `main` preview to the existing `viteplus-staging` project.** PR
+  previews deploy there and would overwrite the `main` preview on every PR
+  push.
+
+## Open questions
+
+- Should the deploy also wait for `publish-docker`, so Docker install docs
+  never precede the image? Waiting adds a few minutes to the deploy.