vue-tui/AGENTS.md

Common Pitfalls & Best Practices

• AGENTS.md is the source of truth. CLAUDE.md is a symlink to it.
• Always use Vue's shallowRef over ref by default. Using ref requires a solid justification and a code comment explaining why deep reactivity is needed.
• Always use defineComponent() to define components. Never use bare { setup() {} } objects — they lack component scope, so inject, watch, and onScopeDispose won't work correctly.
• Vue SFCs must use <script setup> unless there's an explicit reason not to.
• Bug fixes must follow test-first: write a failing test that reproduces the bug, then fix the code and verify the test passes.
• Tests must simulate real user conditions. Non-TTY environments disable chalk colors — use FORCE_COLOR env var so ANSI output is always exercised. A bug invisible in tests but visible in a real terminal is a testing gap, not a minor issue.
• When debugging color/ANSI output in non-TTY environments (e.g. Claude Code shell), use FORCE_COLOR=3 env var to force chalk to output ANSI codes.
• After completing any task, run vp run ready (or vpr ready) to verify: lint, type-check, test all packages, and build.
• Never commit anything under docs/. That directory is for local working notes and specs — it must stay out of git.

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/.

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.