From f2da185bcaf4dbefd0d55a93d717460a555dfbb4 Mon Sep 17 00:00:00 2001
From: Kris McGinnes <kmcginnes@me.com>
Date: Wed, 21 Oct 2026 20:55:40 -0500
Subject: [PATCH 1/2] Drop the Husky self-heal and let vp config update agent
 docs

---
 docs/development.md | 3 +--
 package.json        | 2 +-
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index d77fbef9a..47ed7f264 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -54,8 +54,7 @@ A major bump is also where `pnpm-workspace.yaml` deserves a read. Since pnpm 12,
 
 [Vite+](https://viteplus.dev) runs linting, formatting, type checking, tests, and the pre-commit hook. It's a dev dependency, so `pnpm install` is all the setup it needs. Run `pnpm checks` for lint, format, and type checks, `pnpm test` or `pnpm test:watch` for tests, and `pnpm lint` or `pnpm format` to fix issues. A global `vp` CLI is optional; without one, `pnpm exec vp` works.
 
-- Run `pnpm install` after pulling the switch to Vite+. It moves your pre-commit hook from Husky to `vp staged`.
-- If `pnpm install` prints `core.hooksPath is already set`, your clone or global Git config points hooks somewhere else, and the Vite+ hook isn't installed. Run `git config --unset core.hooksPath` (add `--global` if the value is global), then `pnpm install` again.
+- If the pre-commit hook never runs, or `pnpm install` prints `core.hooksPath is already set`, the Vite+ hook isn't installed, because your clone or global Git config points hooks somewhere else. Clones from before the switch to Vite+ still point at Husky. Run `git config --unset core.hooksPath` (add `--global` if the value is global), then `pnpm run prepare`.
 - In VS Code, install the recommended Vite+ extension pack. In Zed, install `oxc-zed`.
 
 ## Run in development mode
diff --git a/package.json b/package.json
index e0f0d2b46..3e835aec2 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,7 @@
   "author": "amazon",
   "type": "module",
   "scripts": {
-    "prepare": "(git config --unset core.hooksPath husky || cd .) && vp config --no-agent",
+    "prepare": "vp config",
     "lint": "vp lint --fix",
     "check:lint": "vp lint",
     "format": "vp fmt",

From ab292e7d4078c759c6c444d470f13cf464d80bcd Mon Sep 17 00:00:00 2001
From: Kris McGinnes <kmcginnes@me.com>
Date: Wed, 21 Oct 2026 20:55:47 -0500
Subject: [PATCH 2/2] Add the Vite+ block to AGENTS.md and point agents at vp

---
 .github/workflows/ci.yml |  6 ++++++
 AGENTS.md                | 45 +++++++++++++++++++++++++++++++++-------
 docs/agents/testing.md   |  8 +++----
 3 files changed, 48 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 82ec3ddaa..bf4cd9646 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -41,6 +41,12 @@ jobs:
         if: ${{ !cancelled() && steps.install.outcome == 'success' }}
         run: pnpm dedupe --check
 
+      # Install rewrites the Vite+ block in AGENTS.md from the installed
+      # vite-plus. Dependabot bumps skip that, so a stale block fails here.
+      - name: Check the Vite+ block in AGENTS.md is current
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: git diff --exit-code AGENTS.md
+
       - name: Run type, lint, and format checks
         if: ${{ !cancelled() && steps.install.outcome == 'success' }}
         run: pnpm checks
diff --git a/AGENTS.md b/AGENTS.md
index 0353f447c..fd303c221 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -73,16 +73,47 @@ Every code review, including `/code-review`, uses these standards sources:
 
 Pass `REVIEW.md` by path to every reviewer sub-agent, not only the standards one. Sub-agents don't always load this file.
 
+<!-- `vp config` rewrites the Vite+ block below from node_modules/vite-plus on install, so edits inside it are lost. The ignore markers stop the formatter from reflowing it, which would fight that rewrite. -->
+<!-- prettier-ignore-start -->
+<!--VITE PLUS START-->
+
+# Using Vite+, the Unified Toolchain for the Web
+
+This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, and it invokes Vite through `vp dev` and `vp build`. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
+
+Docs are local at `node_modules/vite-plus/docs` or online at https://viteplus.dev/guide/.
+
+## Built-in Commands vs Scripts
+
+`vp <name>` runs a built-in command. `vp run <name>` runs a `package.json` script or a `vite.config.ts` task. Scripts cannot overwrite built-ins, so `vp dev` and `vp run dev` may do different things. Check `package.json` and `vite.config.ts` first, and run `vp run <name>` when the project defines a script or task with that name.
+
+## Tool Versions
+
+Run `vp toolchain` to show versions and relationships in the active Vite+
+release. Add a tool name to select part of the graph. For example, run
+`vp toolchain vite`. Use `--global` to ignore the local `vite-plus` package. Use
+`vp why <package>` to show the package-manager dependency graph.
+
+## Review Checklist
+
+- [ ] Run `vp install` after pulling remote changes and before getting started.
+- [ ] Run `vp check` and `vp test` to format, lint, type check and test changes.
+- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`.
+- [ ] If setup, runtime, or package-manager behavior looks wrong, run `vp env doctor` and include its output when asking for help.
+
+<!--VITE PLUS END-->
+<!-- prettier-ignore-end -->
+
 ## Commands
 
-Run from project root. Prefer these `pnpm` scripts. `vp` subcommands (`vp test`, `vp lint`, `vp fmt`, `vp check`) are fine to run directly, since `vp` resolves the project's pinned Vite+ and its config; use `pnpm exec vp` if the global CLI isn't installed. `vp check` runs format, lint, and type checks. Never invoke `tsc`, `tsgo`, `vitest`, `oxlint`, or `oxfmt` directly or via `pnpx`, because bare tools use the wrong version and miss project context.
+Run from the project root. Bare `tsc`, `tsgo`, `vitest`, `oxlint`, and `oxfmt` use the wrong version and miss project context, so always go through `vp`, never through those tools directly or via `pnpx`. Without the global `vp` CLI, prefix each command with `pnpm exec`. The `pnpm` scripts in `package.json` are aliases for humans.
 
-- `pnpm checks` — all static checks (types + lint + format); default validation for small changes
-- `pnpm check:lint` / `pnpm lint` — lint / lint and fix
-- `pnpm check:format` / `pnpm format` — check / fix formatting
-- `pnpm test` — run all tests
-- `pnpm test <path>` — test files matching a path substring (file, dir, or partial)
-- `pnpm test -t "suite > name"` — test by name, with segments joined by a spaced `>` exactly as the reporter prints them; a single segment such as `-t "renders empty state"` also works (no `--` separator; pnpm forwards args verbatim, unlike npm)
+- `vp check` — format, lint, and type checks; default validation for small changes
+- `vp check --fix` — the same, fixing what it can
+- `vp test` — run all tests once
+- `vp test <path>` — test files matching a path substring (file, dir, or partial)
+- `vp test -t "suite > name"` — test by name, with segments joined by a spaced `>` exactly as the reporter prints them; a single segment such as `-t "renders empty state"` also works
+- `pnpm dedupe --check` — after a dependency change, confirms the lockfile has no drift; CI runs it
 
 ## Agent skills
 
diff --git a/docs/agents/testing.md b/docs/agents/testing.md
index da3d37eaf..041ef53e1 100644
--- a/docs/agents/testing.md
+++ b/docs/agents/testing.md
@@ -4,7 +4,7 @@ Vitest. Tests co-locate with source as `*.test.ts` (or `*.test.tsx` for componen
 
 ## Where tests live
 
-Vitest collects only the projects listed in `test.projects` of the root `vite.config.ts`, currently just `packages/*`. A test file outside those is never collected, and `pnpm test` still reports green, so adding a new top-level test directory means giving it a `vite.config.ts` and adding it to that list.
+Vitest collects only the projects listed in `test.projects` of the root `vite.config.ts`, currently just `packages/*`. A test file outside those is never collected, and `vp test` still reports green, so adding a new top-level test directory means giving it a `vite.config.ts` and adding it to that list.
 
 Each project sets up its own environment. `setupTests.ts` below is registered by `packages/graph-explorer` only. `packages/graph-explorer-proxy-server` has its own setup file, and `packages/shared` has no setup file, so any tests added there must reset their own mocks.
 
@@ -74,9 +74,9 @@ test("filters vertices by type", () => {
 
 Commands are in AGENTS.md.
 
-- Small change: `pnpm checks`, plus `pnpm test <path>` for the area you touched
-- Before a PR, or after touching shared utilities, core providers, or type definitions: `pnpm test`
-- No associated tests (config or type-only change): `pnpm checks`
+- Small change: `vp check`, plus `vp test <path>` for the area you touched
+- Before a PR, or after touching shared utilities, core providers, or type definitions: `vp test`
+- No associated tests (config or type-only change): `vp check`
 
 ## Special cases