docs: reorganize guide document layout

.claude/skills/sync-upstream-dependency-docs/SKILL.md

@@ -12,9 +12,10 @@ allowed-tools: Read, Grep, Glob, Edit, Bash
    package name and its old exact version. Do not treat changelogs, RFC examples,
    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
-   those examples are present.
+   particular, keep every exact Vitest pin in the manual-installation examples in
+   `docs/guide/local-cli.md`, `README.md`, and `packages/cli/README.md` in sync.
+   Project-local upgrade guidance lives in `docs/guide/upgrade-project.md`;
+   `docs/guide/upgrade.md` covers global CLI upgrades.
 4. Preserve the surrounding wording and formatting. Do not rewrite examples whose
    version is intentionally historical or illustrative.
 5. Re-run the searches for the changed packages and inspect the focused diff. No

docs/.vitepress/config.mts

@@ -27,46 +27,32 @@ function rewriteInstallUrls(text: string): string {
     .replaceAll('https://vite.plus', installShUrl);
 }
 
-const taskRunnerGuideItems = [
-  {
-    text: 'Run',
-    link: '/guide/run',
-  },
+const guideSidebar = [
   {
-    text: 'Task Caching',
-    link: '/guide/cache',
+    text: 'Introduction',
     items: [
-      { text: 'Automatic Data Tracking', link: '/guide/automatic-data-tracking' },
-      { text: 'GitHub Actions Cache', link: '/guide/github-actions-cache' },
+      { text: 'Getting Started', link: '/guide/' },
+      { text: 'Global CLI', link: '/guide/global-cli' },
+      { text: 'Project-local CLI', link: '/guide/local-cli' },
+      { text: 'Why Vite+', link: '/guide/why' },
     ],
   },
   {
-    text: 'Running Binaries',
-    link: '/guide/vpx',
-  },
-];
-
-const guideSidebar = [
-  {
-    text: 'Introduction',
+    text: 'Set Up a Project',
     items: [
-      { text: 'Getting Started', link: '/guide/' },
       { text: 'Creating a Project', link: '/guide/create' },
       {
         text: 'Migrate to Vite+',
         link: '/guide/migrate',
         items: [{ text: 'Migration Rules', link: '/guide/migrate-rules' }],
       },
-      { text: 'Installing Dependencies', link: '/guide/install' },
-      { text: 'Environment', link: '/guide/env' },
-      { text: 'Installer Environment Variables', link: '/guide/installer-env-vars' },
-      { text: 'Why Vite+', link: '/guide/why' },
+      { text: 'Update Vite+', link: '/guide/upgrade-project' },
+      { text: 'Package Management', link: '/guide/install' },
     ],
   },
   {
-    text: 'Develop',
+    text: 'Project Toolchain',
     items: [
-      { text: 'Dev', link: '/guide/dev' },
       {
         text: 'Check',
         link: '/guide/check',
@@ -76,22 +62,33 @@ const guideSidebar = [
         ],
       },
       { text: 'Test', link: '/guide/test' },
-    ],
-  },
-  {
-    text: 'Execute',
-    items: taskRunnerGuideItems,
-  },
-  {
-    text: 'Build',
-    items: [
+      { text: 'Dev', link: '/guide/dev' },
       { text: 'Build', link: '/guide/build' },
       { text: 'Pack', link: '/guide/pack' },
+      {
+        text: 'Run',
+        link: '/guide/run',
+      },
+      {
+        text: 'Task Caching',
+        link: '/guide/cache',
+        items: [
+          { text: 'Automatic Data Tracking', link: '/guide/automatic-data-tracking' },
+          { text: 'GitHub Actions Cache', link: '/guide/github-actions-cache' },
+        ],
+      },
+      {
+        text: 'Running Binaries',
+        link: '/guide/vpx',
+      },
+      { text: 'Commit Hooks', link: '/guide/commit-hooks' },
+      { text: 'Monorepo Guide', link: '/guide/monorepo' },
     ],
   },
   {
-    text: 'Maintain',
+    text: 'Global CLI',
     items: [
+      { text: 'Environment', link: '/guide/env' },
       { text: 'Upgrading Vite+', link: '/guide/upgrade' },
       { text: 'Removing Vite+', link: '/guide/implode' },
     ],
@@ -102,11 +99,12 @@ const guideSidebar = [
       { text: 'IDE Integration', link: '/guide/ide-integration' },
       { text: 'CI', link: '/guide/ci' },
       { text: 'Docker', link: '/guide/docker' },
-      { text: 'Commit Hooks', link: '/guide/commit-hooks' },
-      { text: 'Monorepo Guide', link: '/guide/monorepo' },
-      { text: 'Troubleshooting', link: '/guide/troubleshooting' },
     ],
   },
+  {
+    text: 'Reference',
+    items: [{ text: 'Troubleshooting', link: '/guide/troubleshooting' }],
+  },
 ];
 
 export default extendConfig(

docs/config/staged.md

@@ -1,7 +1,6 @@
 # Staged Config
 
-`vp staged` reads staged-file rules from the `staged` block in `vite.config.ts`. See the
-[Commit hooks guide](/guide/commit-hooks).
+`vp staged` reads staged-file rules from the `staged` block in `vite.config.ts`. See the [Commit hooks guide](/guide/commit-hooks).
 
 ## Example
 

docs/guide/ci.md

@@ -10,37 +10,7 @@ You can use `voidzero-dev/setup-vp` to use Vite+ in CI environments.
 
 Set `<setup-vp-version>` in each example to an exact version from the [`setup-vp` releases page](https://github.com/voidzero-dev/setup-vp/releases). You can use a commit SHA instead. Do not use the `v1` tag. The `v1` tag no longer receives updates.
 
-Run `vp migrate` to replace exact `voidzero-dev/setup-vp@v1` references in
-GitHub Actions workflows and composite actions under `.github` with the latest
-exact release known to your Vite+ version. Existing exact versions and commit
-SHAs remain unchanged.
-
-### Automatic Version Updates
-
-Dependabot and Renovate can update exact versions in GitHub Actions workflows.
-
-To use [Dependabot version updates](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates), add a `github-actions` entry to `.github/dependabot.yml`:
-
-```yaml [.github/dependabot.yml]
-version: 2
-updates:
-  - package-ecosystem: github-actions
-    directory: /
-    schedule:
-      interval: weekly
-```
-
-Dependabot checks `uses:` entries in `.github/workflows` each week.
-
-[Renovate's GitHub Actions manager](https://docs.renovatebot.com/modules/manager/github-actions/) detects `uses:` entries by default. You do not need a package rule for `setup-vp`.
-
-When you use a commit SHA, add the exact release tag in a comment. Renovate uses the comment to find updates:
-
-```yaml
-- uses: voidzero-dev/setup-vp@<commit-sha> # <setup-vp-version>
-```
-
-These settings apply only to GitHub Actions workflows. For GitLab CI/CD and Azure Pipelines, update both version values together.
+Run `vp migrate` to replace exact `voidzero-dev/setup-vp@v1` references in GitHub Actions workflows and composite actions under `.github` with the latest exact release known to your Vite+ version. Existing exact versions and commit SHAs remain unchanged.
 
 ## GitHub Actions
 
@@ -125,6 +95,33 @@ The Azure Pipelines template supports Microsoft-hosted Linux, macOS, and Windows
 
 For advanced configuration and the complete parameter reference, see the [`setup-vp` Azure Pipelines documentation](https://github.com/voidzero-dev/setup-vp#azure-pipelines).
 
+## Automatic Version Updates
+
+Dependabot and Renovate can update exact versions in GitHub Actions workflows.
+
+To use [Dependabot version updates](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates), add a `github-actions` entry to `.github/dependabot.yml`:
+
+```yaml [.github/dependabot.yml]
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+```
+
+Dependabot checks `uses:` entries in `.github/workflows` each week.
+
+[Renovate's GitHub Actions manager](https://docs.renovatebot.com/modules/manager/github-actions/) detects `uses:` entries by default. You do not need a package rule for `setup-vp`.
+
+When you use a commit SHA, add the exact release tag in a comment. Renovate uses the comment to find updates:
+
+```yaml
+- uses: voidzero-dev/setup-vp@<commit-sha> # <setup-vp-version>
+```
+
+These settings apply only to GitHub Actions workflows. For GitLab CI/CD and Azure Pipelines, update both version values together.
+
 ## Simplifying Existing Workflows
 
 If you are migrating an existing GitHub Actions workflow, you can often replace large blocks of Node, package-manager, and cache setup with a single `setup-vp` step.

docs/guide/commit-hooks.md

@@ -1,7 +1,6 @@
 # Commit Hooks
 
-Use `vp hooks` to manage the Git hook dispatcher, `vp config` for project setup
-(hooks + agent integration), and `vp staged` to run checks on staged files.
+Use `vp hooks` to manage the Git hook dispatcher, `vp config` for project setup (hooks + agent integration), and `vp staged` to run checks on staged files.
 
 ## Overview
 
@@ -64,10 +63,7 @@ Check the `Dispatcher` and `core.hooksPath` lines to see whether hooks are actua
 
 ### `vp config`
 
-`vp config` configures Vite+ for the current project. It installs the generated Git hook
-dispatcher (unless hooks were disabled with `vp hooks disable`) and can also handle related
-project integration such as agent setup. The hooks directory defaults to `.vite-hooks`, or the
-last directory used by `vp hooks` / `vp config` in this clone:
+`vp config` configures Vite+ for the current project. It installs the generated Git hook dispatcher (unless hooks were disabled with `vp hooks disable`) and can also handle related project integration such as agent setup. The hooks directory defaults to `.vite-hooks`, or the last directory used by `vp hooks` / `vp config` in this clone:
 
 ```bash
 vp config
@@ -76,24 +72,15 @@ vp config --no-hooks
 vp config --no-agent
 ```
 
-Use `--no-hooks` when you want `vp config` to leave the Git hook dispatcher unchanged. Use
-`--no-agent` when you want it to skip updates to existing coding agent instruction files. You can
-pass both flags when you want `vp config` to skip both setup steps. After `vp hooks disable`,
-`vp config` skips reinstalling the dispatcher and points you at `vp hooks enable` instead of
-prompting again.
+Use `--no-hooks` when you want `vp config` to leave the Git hook dispatcher unchanged. Use `--no-agent` when you want it to skip updates to existing coding agent instruction files. You can pass both flags when you want `vp config` to skip both setup steps. After `vp hooks disable`, `vp config` skips reinstalling the dispatcher and points you at `vp hooks enable` instead of prompting again.
 
-You can also set `VP_GIT_HOOKS=0` to disable hook installation from lifecycle scripts such as
-`prepare` or `postinstall`.
+You can also set `VP_GIT_HOOKS=0` to disable hook installation from lifecycle scripts such as `prepare` or `postinstall`.
 
-Project-owned hook scripts such as `.vite-hooks/pre-commit` should be committed to the repository.
-The generated dispatcher and shims under `.vite-hooks/_` are ignored and recreated by `vp config`
-or `vp hooks enable`. Neither command creates or modifies project hook scripts or staged-file
-configuration.
+Project-owned hook scripts such as `.vite-hooks/pre-commit` should be committed to the repository. The generated dispatcher and shims under `.vite-hooks/_` are ignored and recreated by `vp config` or `vp hooks enable`. Neither command creates or modifies project hook scripts or staged-file configuration.
 
 ### `vp staged`
 
-`vp staged` runs staged-file checks using the `staged` config from `vite.config.ts`. To run it
-before each commit, add it to the project-owned pre-commit hook:
+`vp staged` runs staged-file checks using the `staged` config from `vite.config.ts`. To run it before each commit, add it to the project-owned pre-commit hook:
 
 ```bash
 vp staged
@@ -119,12 +106,7 @@ export default defineConfig({
 });
 ```
 
-This is the default Vite+ approach and should replace separate `lint-staged` configuration in most
-projects. When you opt into hooks during `vp create`, Vite+ scaffolds both this configuration and
-the corresponding pre-commit hook. During `vp migrate`, existing hook policy is preserved, and
-the default is introduced only when no existing hook policy is found. Because
-`vp staged` reads from `vite.config.ts`, your staged-file checks stay in the same place as your
-lint, format, test, build, and task-runner config.
+This is the default Vite+ approach and should replace separate `lint-staged` configuration in most projects. When you opt into hooks during `vp create`, Vite+ scaffolds both this configuration and the corresponding pre-commit hook. During `vp migrate`, existing hook policy is preserved, and the default is introduced only when no existing hook policy is found. Because `vp staged` reads from `vite.config.ts`, your staged-file checks stay in the same place as your lint, format, test, build, and task-runner config.
 
 ## Disabling Hooks in Specific Environments
 
@@ -157,8 +139,7 @@ Because the hook itself reads this file, it works even when the committing proce
 
 ## Removing commit hooks
 
-To stop using the Vite+ hook dispatcher in this clone (and keep `prepare` / `vp config` from
-reinstalling it):
+To stop using the Vite+ hook dispatcher in this clone (and keep `prepare` / `vp config` from reinstalling it):
 
 ```bash
 vp hooks disable
@@ -170,17 +151,15 @@ This:
 
 1. Unsets `core.hooksPath` when it points at the Vite+ dispatcher
 2. Removes the generated `<hooks-dir>/_` directory
-3. Records a **local** disable preference so lifecycle scripts skip reinstall until you run
-   `vp hooks enable` again
+3. Records a **local** disable preference so lifecycle scripts skip reinstall until you run `vp hooks enable` again
 
 To re-enable:
 
 ```bash
 vp hooks enable
 ```
 
-If you no longer want hooks for the project at all (shared with teammates), also remove `vp config`
-from the `prepare` or `postinstall` script in `package.json`.
+If you no longer want hooks for the project at all (shared with teammates), also remove `vp config` from the `prepare` or `postinstall` script in `package.json`.
 
 ### Manual equivalent
 
@@ -195,6 +174,4 @@ git config --local vp.hooks.disabled true
 # git config --local vp.hooks.dir .vite-hooks
 ```
 
-Project-owned scripts such as `.vite-hooks/pre-commit` and the `staged` block in `vite.config.ts`
-can remain for later use, or you can remove them separately if the project no longer needs them.
-`vp hooks disable` does **not** delete those project-owned files.
+Project-owned scripts such as `.vite-hooks/pre-commit` and the `staged` block in `vite.config.ts` can remain for later use, or you can remove them separately if the project no longer needs them. `vp hooks disable` does **not** delete those project-owned files.

docs/guide/create.md

@@ -57,8 +57,7 @@ Run `vp create --list` to see the built-in templates and the common shorthand te
 - `--hooks` enables pre-commit hook setup (dispatcher + `.vite-hooks` + `staged` config)
 - `--no-hooks` skips hook setup
 
-After create, manage the dispatcher with `vp hooks status`, `vp hooks disable`, and `vp hooks enable`.
-See the [Commit hooks guide](/guide/commit-hooks).
+After create, manage the dispatcher with `vp hooks status`, `vp hooks disable`, and `vp hooks enable`. See the [Commit hooks guide](/guide/commit-hooks).
 
 ### Dependency build scripts