voidzero-dev · fengmk2 · Aug 18, 2026 · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026
diff --git a/.claude/skills/bump-vite-task/SKILL.md b/.claude/skills/bump-vite-task/SKILL.md
@@ -66,10 +66,10 @@ vite-task changes often affect CLI output, which means snapshot tests need updat
   ```
 - Review each changelog entry and determine if it affects user-facing behavior: new CLI options, changed defaults, new config fields, removed features, etc.
 - The changelog contains links to the corresponding vite-task PRs. For complex changes, check the PR description and code diff (especially any docs changes in the PR) to understand the full scope of the change.
-- If user-facing changes are found, update the relevant docs in `docs/` (e.g., `docs/guide/`, `docs/config/`).
+- If user-facing changes are found, update the relevant docs in `docs/src/` (e.g., `docs/src/guide/`, `docs/src/config/`).
 - Common doc updates include:
-  - **New CLI flags/options**: Update the relevant config doc (e.g., `docs/config/run.md`, `docs/config/build.md`)
-  - **New features or commands**: Add or update the relevant guide page (e.g., `docs/guide/cache.md`)
+  - **New CLI flags/options**: Update the relevant config doc (e.g., `docs/src/config/run.md`, `docs/src/config/build.md`)
+  - **New features or commands**: Add or update the relevant guide page (e.g., `docs/src/guide/cache.md`)
   - **Changed defaults or behavior**: Update any docs that describe the old behavior
   - **Removed/deprecated options**: Remove or mark as deprecated in the relevant docs
 - If no user-facing changes are found, skip this step.

diff --git a/.claude/skills/sync-upstream-dependency-docs/SKILL.md b/.claude/skills/sync-upstream-dependency-docs/SKILL.md
@@ -13,7 +13,7 @@ allowed-tools: Read, Grep, Glob, Edit, Bash
    snapshots, or broad ranges such as `vitest@4.x` as current-version references.
 3. Update references that promise to match Vite+'s currently bundled version. In
    particular, keep every exact Vitest pin in the manual-migration examples in sync,
-   including `docs/guide/migrate.md`, `README.md`, and `packages/cli/README.md` when
+   including `docs/src/guide/migrate.md`, `README.md`, and `packages/cli/README.md` when
    those examples are present.
 4. Preserve the surrounding wording and formatting. Do not rewrite examples whose
    version is intentionally historical or illustrative.

diff --git a/.github/workflows/publish-preview-register.yml b/.github/workflows/publish-preview-register.yml
@@ -421,7 +421,7 @@ jobs:
 
   # Build and push a preview Docker image from the registry bridge build so the
   # image can be verified before a real release. Tagged `pr-<number>`; never
-  # `latest`. See docker/Dockerfile and docs/guide/docker.md.
+  # `latest`. See docker/Dockerfile and docs/src/guide/docker.md.
   #
   # Same-repo PRs only, for now. This job installs the preview package, which
   # executes the PR's code, and pushes the result to the org's GHCR namespace as
@@ -530,7 +530,7 @@ jobs:
               `docker run --rm ${image}:pr-${pr} vp --version`,
               '```',
               '',
-              'See [docs/guide/docker.md](https://github.com/voidzero-dev/vite-plus/blob/main/docs/guide/docker.md) for usage.',
+              'See [docs/src/guide/docker.md](https://github.com/voidzero-dev/vite-plus/blob/main/docs/src/guide/docker.md) for usage.',
             ].join('\n');
             const comments = await github.paginate(github.rest.issues.listComments, {
               owner: context.repo.owner,

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -243,7 +243,7 @@ jobs:
 
   # 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.
+  # exist first). See docker/Dockerfile and docs/src/guide/docker.md.
   publish-docker:
     name: Publish Docker image
     runs-on: ubuntu-latest

diff --git a/AGENTS.md b/AGENTS.md
@@ -54,11 +54,11 @@ vite-plus/
 - **Package-manager behavior**: start at `crates/vp_pm_cli/`.
 - **Managed Node runtime / shims**: start at `crates/vp_js_runtime/`.
 - **Static `vite.config.ts` extraction**: start at `crates/vp_static_config/README.md` and `packages/cli/src/resolve-vite-config.ts`.
-- **Migration behavior**: `docs/guide/migrate-rules.md`.
+- **Migration behavior**: `docs/src/guide/migrate-rules.md`.
 - **Migrator code (`vp migrate`)**: category modules under `packages/cli/src/migration/migrator/` behind the `migrator.ts` barrel; follow `migrator/README.md` when changing migrator code.
 - **Bundled toolchain surfaces**: start with `packages/core/BUNDLING.md` and `packages/cli/BUNDLING.md`.
 - **Generated project agent guidance**: `packages/cli/AGENTS.md` and `packages/cli/src/utils/agent.ts`; do not edit these when the task is only to improve root repo guidance.
-- **Product/repo docs**: root contributor docs live at the repo root and the VitePress site under `docs/` (`docs/guide/`, `docs/config/`); generated agent guidance is separate.
+- **Product/repo docs**: root contributor docs live at the repo root and the VitePress site under `docs/src/` (`docs/src/guide/`, `docs/src/config/`); generated agent guidance is separate.
 - **CLI output behavior**: inspect the relevant code plus `crates/vp_cli_snapshots/tests/cli_snapshots/` (PTY snapshot suite; write new cases here).
 - **Interactive CLI testing (prompts, pickers, keystrokes)**: `crates/vp_cli_snapshots/tests/cli_snapshots/README.md` and `rfcs/interactive-snapshot-tests.md`.
 - **Install-testing against the local build**: `packages/tools/src/local-npm-registry.ts` serves the packed checkout behind a real registry interface; used by PTY snapshot fixtures, ecosystem e2e (`ecosystem-ci/patch-project.ts`), and local `vp migrate`/`vp create` iteration (see `CONTRIBUTING.md`).
@@ -90,7 +90,7 @@ Important distinctions:
 - Do not introduce `vite-task.json`; current Vite+ task configuration lives under `run` in `vite.config.ts`.
 - Do not run `cargo test -p vt` in this repo; Vite Task crates are git dependencies, not local workspace members.
 
-Reference: `docs/guide/run.md` and `docs/config/run.md`.
+Reference: `docs/src/guide/run.md` and `docs/src/config/run.md`.
 
 ## Development Workflow
 
@@ -196,9 +196,9 @@ Use the validation matrix above as the source of truth. For behavior-bearing cha
 - Contributor workflow: `CONTRIBUTING.md`
 - Root scripts: `package.json`
 - Repo config: `vite.config.ts`
-- Vite+ guide: `docs/guide/index.md`
-- Run guide: `docs/guide/run.md`
-- Run config: `docs/config/run.md`
+- Vite+ guide: `docs/src/guide/index.md`
+- Run guide: `docs/src/guide/run.md`
+- Run config: `docs/src/config/run.md`
 - CLI package architecture: `packages/cli/BUNDLING.md`
 - Core package architecture: `packages/core/BUNDLING.md`
 - CLI snapshot runner: `crates/vp_cli_snapshots/tests/cli_snapshots/README.md`

diff --git a/docker/Dockerfile b/docker/Dockerfile
@@ -6,7 +6,7 @@
 # production runtime image: it ships the full toolchain (vite, rolldown, vitest,
 # oxlint, ...) and is meant for use as a build stage, CI image, or devcontainer.
 #
-# For production, use the documented multi-stage pattern (see docs/guide/docker.md)
+# For production, use the documented multi-stage pattern (see docs/src/guide/docker.md)
 # where this image builds the app and the exact Node.js resolved from
 # `.node-version` is copied into a small, vp-free runtime stage.
 

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -112,6 +112,7 @@ const guideSidebar = [
 export default extendConfig(
   withMermaid(
     defineConfig({
+      srcDir: 'src',
       title: 'Vite+',
       titleTemplate: ':title | The Unified Toolchain for the Web',
       description: 'The Unified Toolchain for the Web',
@@ -133,6 +134,8 @@ export default extendConfig(
         ['meta', { name: 'twitter:site', content: '@voidzerodev' }],
       ],
       vite: {
+        // Keep deployment assets out of the documentation bundled with vite-plus.
+        publicDir: resolve(__dirname, '../public'),
         define: {
           __DOCS_ORIGIN__: JSON.stringify(docsOrigin),
           __DOCS_INSTALL_SH_URL__: JSON.stringify(installShUrl),

diff --git a/docs/config/build.md → docs/src/config/build.md b/docs/config/build.md → docs/src/config/build.md
diff --git a/docs/config/check.md → docs/src/config/check.md b/docs/config/check.md → docs/src/config/check.md
diff --git a/docs/config/create.md → docs/src/config/create.md b/docs/config/create.md → docs/src/config/create.md
diff --git a/docs/config/fmt.md → docs/src/config/fmt.md b/docs/config/fmt.md → docs/src/config/fmt.md
diff --git a/docs/config/index.md → docs/src/config/index.md b/docs/config/index.md → docs/src/config/index.md
diff --git a/docs/config/lint.md → docs/src/config/lint.md b/docs/config/lint.md → docs/src/config/lint.md
diff --git a/docs/config/pack.md → docs/src/config/pack.md b/docs/config/pack.md → docs/src/config/pack.md
diff --git a/docs/config/run.md → docs/src/config/run.md b/docs/config/run.md → docs/src/config/run.md
diff --git a/docs/config/staged.md → docs/src/config/staged.md b/docs/config/staged.md → docs/src/config/staged.md
diff --git a/docs/config/test.md → docs/src/config/test.md b/docs/config/test.md → docs/src/config/test.md
diff --git a/docs/guide/automatic-data-tracking.md → docs/src/guide/automatic-data-tracking.md b/docs/guide/automatic-data-tracking.md → docs/src/guide/automatic-data-tracking.md
diff --git a/docs/guide/build.md → docs/src/guide/build.md b/docs/guide/build.md → docs/src/guide/build.md
diff --git a/docs/guide/cache.md → docs/src/guide/cache.md b/docs/guide/cache.md → docs/src/guide/cache.md
diff --git a/docs/guide/check.md → docs/src/guide/check.md b/docs/guide/check.md → docs/src/guide/check.md
diff --git a/docs/guide/ci.md → docs/src/guide/ci.md b/docs/guide/ci.md → docs/src/guide/ci.md
diff --git a/docs/guide/commit-hooks.md → docs/src/guide/commit-hooks.md b/docs/guide/commit-hooks.md → docs/src/guide/commit-hooks.md
diff --git a/docs/guide/create.md → docs/src/guide/create.md b/docs/guide/create.md → docs/src/guide/create.md
diff --git a/docs/guide/dev.md → docs/src/guide/dev.md b/docs/guide/dev.md → docs/src/guide/dev.md
diff --git a/docs/guide/docker.md → docs/src/guide/docker.md b/docs/guide/docker.md → docs/src/guide/docker.md
diff --git a/docs/guide/env.md → docs/src/guide/env.md b/docs/guide/env.md → docs/src/guide/env.md
diff --git a/docs/guide/fmt.md → docs/src/guide/fmt.md b/docs/guide/fmt.md → docs/src/guide/fmt.md
diff --git a/docs/guide/github-actions-cache.md → docs/src/guide/github-actions-cache.md b/docs/guide/github-actions-cache.md → docs/src/guide/github-actions-cache.md
diff --git a/docs/guide/ide-integration.md → docs/src/guide/ide-integration.md b/docs/guide/ide-integration.md → docs/src/guide/ide-integration.md
diff --git a/docs/guide/implode.md → docs/src/guide/implode.md b/docs/guide/implode.md → docs/src/guide/implode.md
diff --git a/docs/guide/index.md → docs/src/guide/index.md b/docs/guide/index.md → docs/src/guide/index.md
diff --git a/docs/guide/install.md → docs/src/guide/install.md b/docs/guide/install.md → docs/src/guide/install.md
diff --git a/docs/guide/installer-env-vars.md → docs/src/guide/installer-env-vars.md b/docs/guide/installer-env-vars.md → docs/src/guide/installer-env-vars.md
diff --git a/docs/guide/lint.md → docs/src/guide/lint.md b/docs/guide/lint.md → docs/src/guide/lint.md
diff --git a/docs/guide/migrate-rules.md → docs/src/guide/migrate-rules.md b/docs/guide/migrate-rules.md → docs/src/guide/migrate-rules.md
diff --git a/docs/guide/migrate.md → docs/src/guide/migrate.md b/docs/guide/migrate.md → docs/src/guide/migrate.md
diff --git a/docs/guide/monorepo.md → docs/src/guide/monorepo.md b/docs/guide/monorepo.md → docs/src/guide/monorepo.md
diff --git a/docs/guide/pack.md → docs/src/guide/pack.md b/docs/guide/pack.md → docs/src/guide/pack.md
diff --git a/docs/guide/run.md → docs/src/guide/run.md b/docs/guide/run.md → docs/src/guide/run.md
diff --git a/docs/guide/test.md → docs/src/guide/test.md b/docs/guide/test.md → docs/src/guide/test.md
diff --git a/docs/guide/troubleshooting.md → docs/src/guide/troubleshooting.md b/docs/guide/troubleshooting.md → docs/src/guide/troubleshooting.md
diff --git a/docs/guide/upgrade.md → docs/src/guide/upgrade.md b/docs/guide/upgrade.md → docs/src/guide/upgrade.md
diff --git a/docs/guide/vpx.md → docs/src/guide/vpx.md b/docs/guide/vpx.md → docs/src/guide/vpx.md
diff --git a/docs/guide/why.md → docs/src/guide/why.md b/docs/guide/why.md → docs/src/guide/why.md
diff --git a/docs/index.md → docs/src/index.md b/docs/index.md → docs/src/index.md
diff --git a/docs/team.md → docs/src/team.md b/docs/team.md → docs/src/team.md
@@ -11,7 +11,7 @@ import {
   VPTeamPageSection,
   VPTeamMembers
 } from '@voidzero-dev/vitepress-theme'
-import { core } from './_data/team'
+import { core } from '../_data/team'
 </script>
 
 <VPTeamPage>

diff --git a/packages/cli/build.ts b/packages/cli/build.ts
@@ -910,33 +910,22 @@ export default toolchain;
   console.log(`  Created ./versions (${Object.keys(versions).length} tools)`);
 }
 
-/**
- * Copy the docs source tree into docs/, preserving relative paths.
- * Generated VitePress output and installed dependencies are excluded so the package
- * only ships authoring sources and referenced assets.
- */
 async function copyBundledDocs() {
   console.log('\nCopying bundled docs...');
 
-  const docsSourceDir = join(projectDir, '..', '..', 'docs');
+  // Keep site tooling and deployment assets outside the published package.
+  const docsSourceDir = join(projectDir, '..', '..', 'docs', 'src');
   const docsTargetDir = join(projectDir, 'docs');
 
   if (!existsSync(docsSourceDir)) {
     console.log('  Docs source directory not found, skipping docs copy');
     return;
   }
 
-  const skipPrefixes = ['node_modules', '.vitepress/cache', '.vitepress/dist'];
   await rm(docsTargetDir, { recursive: true, force: true });
-  await cp(docsSourceDir, docsTargetDir, {
-    recursive: true,
-    filter: (src) => {
-      const rel = relative(docsSourceDir, src).replaceAll('\\', '/');
-      return !skipPrefixes.some((prefix) => rel === prefix || rel.startsWith(`${prefix}/`));
-    },
-  });
+  await cp(docsSourceDir, docsTargetDir, { recursive: true });
 
-  console.log('  Copied docs to docs/ (with paths preserved)');
+  console.log('  Copied docs/src to docs/');
 }
 
 async function syncReadmeFromRoot() {

diff --git a/packages/cli/src/oxlint-plugin.ts b/packages/cli/src/oxlint-plugin.ts
@@ -12,7 +12,7 @@ import viteConfigEntryBasenames from './vite-config-entry-basenames.json' with {
 
 // `declare module 'vitest…'` and `declare module '@vitest/browser…'` are
 // intentionally preserved by `vp migrate` (see migration's import_rewriter and
-// docs/guide/migrate.md) — `vite-plus/test*` is a thin re-export of upstream
+// docs/src/guide/migrate.md) — `vite-plus/test*` is a thin re-export of upstream
 // `vitest*`, so type augmentations have to target the upstream module identity
 // to merge correctly. Autofixing those module declarations here would split the
 // augmentation away from what imports actually resolve through.

diff --git a/rfcs/create-org-default-templates.md b/rfcs/create-org-default-templates.md
@@ -803,21 +803,21 @@ plumbing.
 Shipped on branch `vp-create-support-org` (PR #1398). Concrete
 landings:
 
-| Module                                          | Role                                                                                                                 |
-| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `packages/cli/src/create/org-manifest.ts`       | `parseOrgScopedSpec`, `readOrgManifest`, schema validation (incl. `__vp_` reserved-prefix check).                    |
-| `packages/cli/src/create/org-resolve.ts`        | `resolveOrgManifestForCreate`, `getConfiguredDefaultTemplate`, picker / `--no-interactive` table dispatch.           |
-| `packages/cli/src/create/org-picker.ts`         | `pickOrgTemplate` interactive picker, escape-hatch entry, context-aware filtering.                                   |
-| `packages/cli/src/create/org-tarball.ts`        | `ensureOrgPackageExtracted`, `resolveBundledPath`, `sanitizeHostForPath`, integrity verification, mode preservation. |
-| `packages/cli/src/create/templates/bundled.ts`  | `executeBundledTemplate` (directory-copy scaffold for relative-path manifest entries).                               |
-| `packages/cli/src/create/discovery.ts`          | `bundledLocalPath` + `skipShorthand` parameters threading manifest results into the existing template flow.          |
-| `packages/cli/src/create/bin.ts`                | Unified monorepo branch (builtin + bundled), git-init prompt, `injectCreateDefaultTemplate` for `@org` monorepos.    |
-| `packages/cli/src/create/utils.ts`              | `ensureGitignoreNodeModules` post-`git init` guarantee.                                                              |
-| `packages/cli/src/define-config.ts`             | `create: { defaultTemplate?: string }` augmentation on `UserConfig`.                                                 |
-| `packages/cli/src/migration/migrator.ts`        | `injectCreateDefaultTemplate` helper (called from `bin.ts`, gated on bundled monorepo).                              |
-| `packages/cli/src/utils/npm-config.ts`          | `.npmrc` parser, `getNpmRegistry(scope?)`, `getNpmAuthHeader(url)`, `fetchNpmResource` (401/403 retry).              |
-| `packages/cli/src/resolve-vite-config.ts`       | `findWorkspaceRoot` exported for the default-template walk-up.                                                       |
-| `docs/guide/create.md`, `docs/config/create.md` | Authoring guide and `create.defaultTemplate` reference.                                                              |
+| Module                                                  | Role                                                                                                                 |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `packages/cli/src/create/org-manifest.ts`               | `parseOrgScopedSpec`, `readOrgManifest`, schema validation (incl. `__vp_` reserved-prefix check).                    |
+| `packages/cli/src/create/org-resolve.ts`                | `resolveOrgManifestForCreate`, `getConfiguredDefaultTemplate`, picker / `--no-interactive` table dispatch.           |
+| `packages/cli/src/create/org-picker.ts`                 | `pickOrgTemplate` interactive picker, escape-hatch entry, context-aware filtering.                                   |
+| `packages/cli/src/create/org-tarball.ts`                | `ensureOrgPackageExtracted`, `resolveBundledPath`, `sanitizeHostForPath`, integrity verification, mode preservation. |
+| `packages/cli/src/create/templates/bundled.ts`          | `executeBundledTemplate` (directory-copy scaffold for relative-path manifest entries).                               |
+| `packages/cli/src/create/discovery.ts`                  | `bundledLocalPath` + `skipShorthand` parameters threading manifest results into the existing template flow.          |
+| `packages/cli/src/create/bin.ts`                        | Unified monorepo branch (builtin + bundled), git-init prompt, `injectCreateDefaultTemplate` for `@org` monorepos.    |
+| `packages/cli/src/create/utils.ts`                      | `ensureGitignoreNodeModules` post-`git init` guarantee.                                                              |
+| `packages/cli/src/define-config.ts`                     | `create: { defaultTemplate?: string }` augmentation on `UserConfig`.                                                 |
+| `packages/cli/src/migration/migrator.ts`                | `injectCreateDefaultTemplate` helper (called from `bin.ts`, gated on bundled monorepo).                              |
+| `packages/cli/src/utils/npm-config.ts`                  | `.npmrc` parser, `getNpmRegistry(scope?)`, `getNpmAuthHeader(url)`, `fetchNpmResource` (401/403 retry).              |
+| `packages/cli/src/resolve-vite-config.ts`               | `findWorkspaceRoot` exported for the default-template walk-up.                                                       |
+| `docs/src/guide/create.md`, `docs/src/config/create.md` | Authoring guide and `create.defaultTemplate` reference.                                                              |
 
 ## Testing
 

diff --git a/rfcs/cwd-flag.md b/rfcs/cwd-flag.md
@@ -344,7 +344,7 @@ All changes live in the Rust layers; no upstream Vite or tsdown changes are requ
 - Picker: reuse `vt_select` and `vt_workspace`, both already dependencies via the `vt` crates.
 - `defaultPackage`: extend the `VitePlusConfigLoader` static extraction the same way `run` config is loaded, and add `defaultPackage?: string` to `packages/cli/src/define-config.ts`.
 - `packages/cli/src/pack-bin.ts` needs no change: positional handling is untouched and `-C` never reaches it.
-- Docs: a `-C` entry in the global CLI docs, `docs/guide/monorepo.md` "App Commands", and a `docs/config/` page for the new key.
+- Docs: a `-C` entry in the global CLI docs, `docs/src/guide/monorepo.md` "App Commands", and a `docs/src/config/` page for the new key.
 
 ## Compatibility
 

diff --git a/rfcs/deploy-docs-on-release.md b/rfcs/deploy-docs-on-release.md
@@ -294,7 +294,7 @@ after the deploy get the new script together with the new binaries.
 ## 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
+  problem 2 but not problem 1, and lets `docs/src/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.

diff --git a/rfcs/dev-engines.md b/rfcs/dev-engines.md
@@ -432,7 +432,7 @@ Both are intentionally separated from this PR: the per-entry fallback threads `o
 
 ### Phase 5: Documentation and tests
 
-1. Update `docs/guide/env.md`, `docs/guide/install.md`, `docs/config/*` as applicable.
+1. Update `docs/src/guide/env.md`, `docs/src/guide/install.md`, `docs/src/config/*` as applicable.
 2. ~~Update [rfcs/package-manager-detection.md](./package-manager-detection.md) (move `devEngines.packageManager` from Future Enhancements into the algorithm) and [rfcs/env-command.md](./env-command.md) (resolution chain).~~ Done alongside this RFC, together with [rfcs/js-runtime.md](./js-runtime.md) and [rfcs/migration-command.md](./migration-command.md).
 3. Snap tests (local and global) covering: pin into devEngines, pin with existing `.node-version`, unpin from devEngines, install with `devEngines.packageManager` (exact, range, array, unsupported name, conflict with `packageManager` field), doctor conflict output, create/migrate output.
 4. Rust unit tests alongside the existing suites in `package_manager.rs` and `package_json.rs`.

diff --git a/rfcs/docker-image.md b/rfcs/docker-image.md
@@ -272,7 +272,7 @@ exercises the real build path.
 
 ### Docs example verification
 
-The Dockerfile patterns documented below (and in `docs/guide/docker.md`) are kept
+The Dockerfile patterns documented below (and in `docs/src/guide/docker.md`) are kept
 honest by a reproduction repo whose GitHub Actions build and smoke-test each
 example end to end (build the image, run the container, assert `HTTP 200`, and
 assert the SSR runtime Node.js matches the pinned `.node-version`):
@@ -442,7 +442,7 @@ docker run --rm -it -v "$PWD:/app" -w /app ghcr.io/voidzero-dev/vite-plus vp bui
 - Q2 plan: [#1324](https://github.com/voidzero-dev/vite-plus/issues/1324)
 - JS runtime management: [`js-runtime.md`](./js-runtime.md)
 - Node.js signature verification: [`verify-node-shasums-signature.md`](./verify-node-shasums-signature.md)
-- CI guide: `docs/guide/ci.md`
+- CI guide: `docs/src/guide/ci.md`
 - Distribution prior art: pnpm <https://pnpm.io/docker>, Deno <https://github.com/denoland/deno_docker>,
   mise <https://mise.jdx.dev/mise-cookbook/docker.html>, Turborepo
   <https://turborepo.dev/docs/guides/tools/docker>, distroless

diff --git a/rfcs/migrate-existing-projects.md b/rfcs/migrate-existing-projects.md
@@ -2,7 +2,7 @@
 
 - Status: Implemented on `rfc/migrate-upgrade-path`; end-to-end browser-mode verification remains (see Follow-ups)
 - Depends on: [#1588 replace @voidzero-dev/vite-plus-test with upstream vitest](https://github.com/voidzero-dev/vite-plus/pull/1588) (merged, `342fd2f4`)
-- Related: `docs/guide/upgrade.md`, [migration-command.md](./migration-command.md), [upgrade-command.md](./upgrade-command.md)
+- Related: `docs/src/guide/upgrade.md`, [migration-command.md](./migration-command.md), [upgrade-command.md](./upgrade-command.md)
 
 ## Goal: upgrade in two commands
 
@@ -181,5 +181,5 @@ The matching Oxlint/autofix behavior is covered by the local `lint-vite-plus-imp
 
 - Verify the browser-mode upgrade across pnpm/npm/yarn; simplify package-local provisioning only if strict peer and optimizer resolution remain correct.
 - Add an end-to-end check on a real `0.1.x` project.
-- Update `docs/guide/upgrade.md` / the release-notes prompt to the `vp upgrade && vp migrate` flow once shipped, and `npm deprecate @voidzero-dev/vite-plus-test`.
+- Update `docs/src/guide/upgrade.md` / the release-notes prompt to the `vp upgrade && vp migrate` flow once shipped, and `npm deprecate @voidzero-dev/vite-plus-test`.
 - Optional `vp migrate --check` (detection-only, exit code signals an available upgrade) for CI.