docs: refresh root agent guide (#2072)

## Summary

Refresh the root `AGENTS.md` guidance to match the current repository
structure and test workflow.

- Remove stale references to the deleted `packages/test` package and
document that `vite-plus/test*` is now generated
from upstream Vitest shims in `packages/cli`.
- Update the repository map with current crates and package ownership.
- Clarify that new CLI snapshot coverage should use the PTY-based runner
introduced in #2052, while legacy snap-test
trees are migration-only.
- Update validation guidance and references for the current snapshot
test commands.

Author: jong-kyung

AGENTS.md

@@ -22,25 +22,33 @@ High-signal repo map:
 
 ```
 vite-plus/
-├── packages/cli/              # Published vite-plus package, JS CLI, docs, templates, snap tests, NAPI binding
+├── packages/cli/              # Published vite-plus package, JS CLI, docs, templates, legacy snap tests, NAPI binding
 │   ├── src/bin.ts             # JS entrypoint and local CLI dispatch
+│   ├── src/resolve-test.ts    # Resolves upstream Vitest for `vp test`
 │   ├── src/utils/agent.ts     # Generated agent-file marker/update logic
 │   ├── binding/               # Rust NAPI binding used by the local CLI
-│   ├── snap-tests/            # Local CLI output snapshots
-│   └── snap-tests-global/     # Global CLI output snapshots
-├── packages/core/             # @voidzero-dev/vite-plus-core bundled toolchain surfaces
-├── packages/test/             # @voidzero-dev/vite-plus-test Vitest-compatible exports
-├── packages/prompts/          # Prompt UI/helpers package
-├── packages/tools/            # Repo tooling
-├── crates/vite_cli_snapshots/ # PTY snapshot test runner + vpt helper (dev-only, new CLI tests)
+│   ├── snap-tests/            # Legacy local CLI output snapshots
+│   └── snap-tests-global/     # Legacy global CLI output snapshots
+├── packages/core/             # @voidzero-dev/vite-plus-core bundled Vite/Rolldown/tsdown/VitePress surfaces
+├── packages/prompts/          # Prompt UI/helpers package, including snapshot milestones
+├── packages/tools/            # Repo tooling, local npm registry, legacy snap migrator
+├── crates/vite_cli_snapshots/ # PTY snapshot test runner + vpt helper (new CLI tests)
+├── crates/vite_command/       # Shared command execution helpers
+├── crates/vite_error/         # Shared error types
 ├── crates/vite_global_cli/    # Standalone global vp binary and top-level command routing
-├── crates/vite_pm_cli/        # Package-manager command surface
 ├── crates/vite_install/       # Package-manager detection/install behavior
+├── crates/vite_installer/     # Installer binary support
 ├── crates/vite_js_runtime/    # Managed Node.js runtime support
+├── crates/vite_migration/     # Rust migration helpers
+├── crates/vite_pm_cli/        # Package-manager command surface
+├── crates/vite_setup/         # Setup helpers
+├── crates/vite_shared/        # Shared Rust env config, tracing, output, utilities
 ├── crates/vite_static_config/ # Static extraction of vite.config.* data
-└── crates/vite_shared/        # Shared Rust env config, tracing, output, utilities
+└── crates/vite_trampoline/    # Windows shim trampoline
 ```
 
+`packages/test` is no longer tracked. The public test API is `vite-plus/test*`, generated by `packages/cli/build.ts` as shims over upstream `vitest` and `@vitest/browser*` exports.
+
 ## Where to Start
 
 - **JS-backed CLI behavior**: start at `packages/cli/src/bin.ts` and nearby `packages/cli/src/**` files.
@@ -51,10 +59,10 @@ vite-plus/
 - **Static `vite.config.ts` extraction**: start at `crates/vite_static_config/README.md` and `packages/cli/src/resolve-vite-config.ts`.
 - **Migration behavior**: `docs/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`, `packages/cli/BUNDLING.md`, and `packages/test/BUNDLING.md`.
+- **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.
-- **CLI output behavior**: inspect the relevant code plus `crates/vite_cli_snapshots/tests/cli_snapshots/` (new PTY snapshot suite; write new cases here) or the legacy `packages/cli/snap-tests/` / `packages/cli/snap-tests-global/` trees.
+- **CLI output behavior**: inspect the relevant code plus `crates/vite_cli_snapshots/tests/cli_snapshots/` (PTY snapshot suite; write new cases here). Legacy `packages/cli/snap-tests/` and `packages/cli/snap-tests-global/` are migration-only.
 - **Interactive CLI testing (prompts, pickers, keystrokes)**: `crates/vite_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 install snap fixtures (`localVitePlusPackages`), ecosystem e2e (`ecosystem-ci/patch-project.ts`), and local `vp migrate`/`vp create` iteration (see `CONTRIBUTING.md`).
 
@@ -65,7 +73,7 @@ vite-plus/
 ```bash
 vp dev       # Vite dev server
 vp build     # Vite + Rolldown build
-vp test      # Bundled Vitest
+vp test      # Bundled upstream Vitest
 vp lint      # Oxlint
 vp fmt       # Oxfmt
 vp check     # Format/lint/type-check workflow
@@ -77,7 +85,8 @@ vpr build    # Shorthand for vp run build
 
 Important distinctions:
 
-- `vp test` is a built-in command. `vp run test` runs a `package.json` script or `vite.config.ts` run task named `test`.
+- `vp test` is a built-in command that executes upstream Vitest. `vp run test` runs a `package.json` script or `vite.config.ts` run task named `test`.
+- User-facing test imports should stay on `vite-plus/test*`; do not recreate `@voidzero-dev/vite-plus-test`.
 - Existing `package.json` scripts are first-class `vp run <script>` targets and are not cached by default.
 - Define `run.tasks` in `vite.config.ts` when a task needs explicit command config, default caching, dependencies, input tracking, or environment tracking.
 - A task name can come from `package.json` or `vite.config.ts`, but not both.
@@ -108,15 +117,15 @@ Use `pnpm bootstrap-cli` when you need to validate the installed global CLI at `
 
 Choose checks by change type:
 
-| Change type                   | Useful validation                                                                                    |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
-| Docs-only / agent-guide edits | Check referenced paths and commands; run `git diff --check -- <files>`                               |
-| TypeScript or JS CLI behavior | `vp check`, `pnpm test:unit`, plus focused package tests when available                              |
-| Rust CLI/crate behavior       | `just check`, `just test`, `just lint`                                                               |
-| CLI output or command UX      | `just snapshot-test <filter>` (new PTY runner); legacy snap tests + `git diff` while migration lasts |
-| Global CLI behavior           | `pnpm bootstrap-cli`, `vp --version`, then relevant global snap tests                                |
-| Release/build behavior        | `just build`                                                                                         |
-| Pre-merge/full validation     | `pnpm bootstrap-cli && pnpm test && git status`                                                      |
+| Change type                   | Useful validation                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------------------- |
+| Docs-only / agent-guide edits | Check referenced paths and commands; run `git diff --check -- <files>`                      |
+| TypeScript or JS CLI behavior | `vp check`, `pnpm test:unit`, plus focused package tests when available                     |
+| Rust CLI/crate behavior       | `just check`, `just test`, `just lint`                                                      |
+| CLI output or command UX      | `just snapshot-test <filter>` (PTY runner); `UPDATE_SNAPSHOTS=1` to accept reviewed changes |
+| Global CLI behavior           | `pnpm bootstrap-cli`, `vp --version`, or `just snapshot-test-global <filter>`               |
+| Release/build behavior        | `just build`                                                                                |
+| Pre-merge/full validation     | `pnpm bootstrap-cli && pnpm test && git status`                                             |
 
 Use `vp check --fix` only when you intentionally want formatting or lint fixes applied.
 
@@ -127,14 +136,15 @@ Use `vp check --fix` only when you intentionally want formatting or lint fixes a
 ```bash
 just snapshot-test                    # build vp, run everything
 just snapshot-test <name-filter>
+just snapshot-test-global <name-filter>  # skip local flavor when no JS build is available
 UPDATE_SNAPSHOTS=1 just snapshot-test <name-filter>   # record/accept snapshots
 ```
 
-Snapshot mismatches fail the run with a unified diff and write `<case>.md.new`; recorded `.md` snapshots are reviewed like code and committed with the fixture. Steps are argv arrays (no shell); use `vpt` subcommands instead of coreutils so cases stay platform-identical.
+Snapshot mismatches fail the run with a unified diff and write `<case>.md.new`; recorded `.md` snapshots are reviewed like code and committed with the fixture. Steps are argv arrays (no shell); use `vpt` subcommands instead of coreutils so cases stay platform-identical. Cases declare `vp = "local" | "global" | ["local", "global"]`; local-flavor cases require a fresh `packages/cli/dist`.
 
 ### Snap tests (legacy, being migrated)
 
-The old trees `packages/cli/snap-tests/` and `packages/cli/snap-tests-global/` still run in CI during the migration but must not receive new cases; convert them with `tool migrate-snap-tests` instead (see the runner README).
+The old trees `packages/cli/snap-tests/` and `packages/cli/snap-tests-global/` still run in CI during the migration but must not receive new cases; convert them with `node packages/tools/src/bin.js migrate-snap-tests ...` instead (see the runner README).
 
 ```bash
 pnpm -F vite-plus snap-test
@@ -173,7 +183,7 @@ Use the validation matrix above as the source of truth. For behavior-bearing cha
 ## Common Pitfalls
 
 - **Treating Vite+ as only Vite Task**: Vite Task is integrated, but this repo spans CLI, runtime, package management, bundled packages, create/migrate, docs, and upstream integration.
-- **Looking for local `crates/vite_task`**: it does not exist here. Check `Cargo.toml` for git dependency wiring.
+- **Looking for local `packages/test` or `crates/vite_task`**: neither is tracked here. Check `packages/cli/BUNDLING.md` for test shims and `Cargo.toml` for Vite Task git dependency wiring.
 - **Confusing built-ins with scripts**: `vp test` and `vp run test` can do different things.
 - **Trusting snap-test exit status alone**: always inspect snapshot diffs.
 
@@ -203,5 +213,5 @@ Use the validation matrix above as the source of truth. For behavior-bearing cha
 - Run config: `docs/config/run.md`
 - CLI package architecture: `packages/cli/BUNDLING.md`
 - Core package architecture: `packages/core/BUNDLING.md`
-- Test package architecture: `packages/test/BUNDLING.md`
+- CLI snapshot runner: `crates/vite_cli_snapshots/tests/cli_snapshots/README.md`
 - Generated agent guidance: `packages/cli/AGENTS.md`, `packages/cli/src/utils/agent.ts`