# AGENTS Guidelines

## Local Docs First

- After dependencies are installed, prefer reading local package docs under `node_modules/weapp-vite/dist/docs/` first.
- Start with `node_modules/weapp-vite/dist/docs/index.md`, then read `README.md` and `mcp.md` as needed.
- Prefer local package docs over stale model memory or old web pages when command behavior is unclear.

## CLI Entry

- This project supports both `weapp-vite` and `wv` CLI commands.
- Treat `weapp-vite dev` and `wv dev` as equivalent forms.
- Prefer project scripts such as `pnpm dev`, `pnpm build`, `pnpm open`, and `pnpm g` before ad-hoc shell commands.
- Use `weapp-vite prepare` or `wv prepare` when managed support files under `.weapp-vite/` need to be refreshed.
- Prefer `weapp-vite screenshot` or `wv screenshot` for mini-program screenshot acceptance.
- Prefer `weapp-vite compare` or `wv compare` for mini-program screenshot diff, baseline comparison, and visual regression checks.
- Prefer `weapp-vite ide logs --open` or `wv ide logs --open` for DevTools terminal log bridging.
- Do not default to generic browser screenshot tools when the target is the mini-program runtime in WeChat DevTools.

## AI Intent Routing

- When the request mentions screenshot, 截图, 页面快照, runtime screenshot, or capture the current mini-program page, default to `weapp-vite screenshot` / `wv screenshot`.
- When the request mentions screenshot compare, 截图对比, diff, baseline, visual regression, 像素对比, or acceptance comparison, default to `weapp-vite compare` / `wv compare`.
- Treat these commands as the primary screenshot contract for AI workflows in this project.
- Only fall back to generic browser screenshot tools when the target is explicitly the web runtime instead of WeChat DevTools.

## Weapp-vite Workflow

- Keep `vite.config.ts` as the source of truth for `weapp` config, output behavior, and IDE/MCP automation.
- Confirm `weapp.srcRoot`, routes, subpackages, and auto-import strategy before broad refactors.
- Prefer minimal scoped verification: targeted `pnpm build`, targeted tests, then broader checks only when required.
- If editing package source in a monorepo dependency, rebuild the touched package before validating downstream apps to avoid stale `dist`.
- Keep CLI ownership explicit: native `weapp-vite` commands first, IDE passthrough second.
- For Rust/native acceleration, treat JS ↔ Rust boundary crossings as a primary performance cost. Prefer batch analysis that sends source once, parses once, and returns structured results; only put fine-grained native APIs on hot paths when profiling proves a net win.
- Keep native AST fast paths optional and explicitly enabled. They must fall back to Babel/Oxc/Vue compiler behavior on load, parse, or runtime failure, and new native coverage needs correctness tests plus real profiling.

## SVG Icons

- Icons render via the `weapp-svg-icon` npm component, referenced as `weapp-svg-icon/index` in `usingComponents`.
- Icon data is tree-shaken from `@iconify-json/ph` and `@iconify-json/solar` into a minimal set by `scripts/generate-svg-icons.mjs`.
- After adding or changing icons in source (new `ph:*` / `solar:*` names), run `npm run gen:icons` to regenerate the minimal data, then `npx patch-package weapp-svg-icon` to refresh `patches/weapp-svg-icon+1.0.0.patch`.
- IMPORTANT: `wv build` caches compiled npm mini-program packages by `package.json` dependency hash (see `node_modules/weapp-vite/.cache/`). Regenerating only `miniprogram_dist/index.js` does NOT invalidate this cache, so new icons silently stay missing. After `gen:icons`, clear the cache before building, e.g. remove `node_modules/weapp-vite/.cache/-.json`, so the stale `dist/miniprogram_npm/weapp-svg-icon/` is rebuilt.

## WeChat DevTools

- Before using screenshot, preview, upload, automator, or `--open`, ensure WeChat DevTools is logged in and the service port is enabled.
- `wv open`, `wv dev -o`, and `wv build -o` use the official DevTools CLI first, then connect automator; if the IDE is open but automator is unavailable, run `wv ide doctor --json` before retrying.
- Use `--ide-open-strategy automator` only for explicit compatibility debugging; do not treat it as the default startup path.
- Prefer writing screenshots to workspace paths such as `.tmp/acceptance.png`.

## AI Skills

- Recommend installing shared skills with `npx skills add sonofmagic/skills`.
- In Codex/Claude environments, prefer these skills first when available:
  - `$weapp-vite-best-practices` for config, build, subpackage, route, DevTools CLI orchestration, and screenshot/compare command work.
  - `$weapp-vite-vue-sfc-best-practices` for `.vue` SFC macros, JSON blocks, and template compatibility.
  - `$release-and-changeset-best-practices` for issue delivery, pnpm change intents, repoctl release decisions, and PR workflow.
  - `$docs-and-website-sync` when documentation or AI guidance must be refreshed together with code changes.
  - Use `$weapp-vite-best-practices` for stateful HMR, pluginRoot/dist-plugin, Web runtime compatibility, and native AST profiling; use `$wevu-best-practices` for `wevu/router` navigation semantics.
  - Use `$weapp-devtools-e2e-best-practices` for serialized DevTools runtime suites, shared automator sessions, and known host compatibility skips.
  - `$native-to-weapp-vite-wevu-migration` when migrating native mini-program projects to `weapp-vite + native`, or further toward Vue SFC / wevu.

## Native Mini-program Authoring

- Keep native page/component structure consistent with the template unless there is a clear migration goal.
- Prefer `weapp-vite generate` or `wv generate` for new app/page/component scaffolds.
- If migrating this project, first decide whether the target is `weapp-vite + native` or a further Vue SFC / `wevu` migration, then keep each migration wave explicit.