docs: harden agent UI/quality instructions

Register golden paths, YAGNI, and verify:ui in app instructions and Cursor rules.

Co-authored-by: zuiidea <zuiiidea@gmail.com>

apps/basic/.github/instructions/README.md

@@ -4,11 +4,13 @@ This directory contains scoped instruction files used by AI coding agents.
 
 ## Files
 
-- `frontend.instructions.md`: UI/routes/components/style changes
+- `frontend.instructions.md`: UI/routes/components/style changes (includes golden paths and `verify:ui`)
 - `testing.instructions.md`: Playwright/MSW/test changes
 - `api.instructions.md`: API client/schema/handler changes
 - `refactor.instructions.md`: behavior-preserving cleanup and deduplication
 
+UI golden paths and Ant Design/token rules live in `frontend.instructions.md`.
+
 ## Authoring Rules
 
 - Keep each file focused on one domain.

apps/basic/.github/instructions/api.instructions.md

@@ -13,6 +13,7 @@ Maintain strict API contracts and consistent server/client mock behavior.
 ## Do
 
 - Keep request/response shapes schema-driven and type-safe.
+- New endpoints and client mutations/queries must use Zod schemas at the boundary.
 - Reuse endpoint constants and shared response helpers.
 - Keep handler response envelope consistent (`code`, `data`, `message`).
 - Ensure mock handlers reflect real API behavior and error semantics.

apps/basic/.github/instructions/frontend.instructions.md

@@ -1,8 +1,7 @@
 ---
-
-## applyTo: "src/\*_/_.{ts,tsx,css}"
-
-description: "Use when editing React UI, route pages, components, styles, layout, i18n text, or Ant Design behavior. Keywords: frontend, component, page, ui, layout, style, antd, i18n."
+applyTo: "src/**/*.{ts,tsx,css}"
+description: "Use when editing React UI, route pages, components, styles, layout, or Ant Design behavior. Keywords: frontend, component, page, ui, layout, style, antd."
+---
 
 # Frontend Instructions
 
@@ -14,9 +13,8 @@ Keep frontend changes predictable, minimal, and reusable for AI-assisted edits.
 
 - Preserve existing route contracts and UI behavior unless explicitly asked.
 - Prefer reusable components and hooks over copy-paste logic.
-- Keep styles token-driven using existing theme/store patterns.
+- Keep styles token-driven using `src/theme/theme.config.ts` and `theme.useToken()`.
 - For Ant Design styling, follow this priority: component native API (`variant`/`type`/`size`/`styles`/`classNames`) -> `theme.useToken()` with inline `style` -> `className` + external CSS.
-- Keep translations compatible with Lingui macros and catalogs.
 - Follow current folder conventions under src/components and src/routes.
 
 ## Do Not
@@ -24,9 +22,40 @@ Keep frontend changes predictable, minimal, and reusable for AI-assisted edits.
 - Do not introduce new UI libraries when Ant Design already covers the need.
 - Do not bypass existing theme/store abstractions with hardcoded global state.
 - Do not write CSS overrides first when props or semantic `styles` can express the same UI.
+- Do not put literal `#hex` / `rgb()` / `hsl()` colors in business TSX (use `theme.config` or tokens).
 - Do not refactor unrelated files in the same change.
 
+## Golden paths
+
+Classify the page archetype, open the golden path, copy file split and data flow, then replace domain schema/API/columns only.
+
+| Archetype | Path |
+|-----------|------|
+| ListCRUD | `src/routes/_auth/users/` (includes `-Toolbar.tsx`, `-FormModal.tsx`) |
+| Auth | `src/routes/login/` |
+| Dashboard | `src/routes/_auth/dashboard/` |
+| Shell | `src/components/Layout/` |
+| Error | `src/components/NotFound/`, `src/components/RouteError.tsx` |
+
+## Ant Design and tokens
+
+- Prefer `Flex` / `Space` / `Row` / `Col` for layout intent.
+- Brand and seed tokens live only in `src/theme/theme.config.ts` (optional `colorPrimary`).
+- Menu/table chrome algorithms stay in `hooks/tokenBuilders.ts`.
+
+## Div and CSS exceptions
+
+- Native `div` is allowed for `ref` measure slots, scroll containers, and third-party DOM requirements.
+- New CSS files must be on the `verify:ui` allowlist (see `scripts/verify-ui.mjs`); prefer tokens over new CSS.
+
+## YAGNI
+
+- Do not extract a shared hook/component without a third call site.
+- Do not add parallel abstractions when an existing shell (`DataTable`, `FilterToolbar`, `FormModal`, `useResourceCRUD`) covers the need.
+
 ## Validation
 
-- Run: `vp check --no-fmt`
-- For UI flow changes, run focused e2e where possible.
+- Run: `pnpm check` (or `vp check --no-fmt`)
+- Run: `pnpm verify:ui` (local/Agent gate; not CI in phase 1)
+- On failure: fix the same violation set at most twice, then stop and shrink scope
+- For UI flow changes, run focused e2e where possible

apps/basic/.github/instructions/refactor.instructions.md

@@ -14,6 +14,7 @@ Reduce duplication while preserving behavior and public contracts.
 
 - Keep refactors incremental and scoped to one concern per change.
 - Prefer extracting shared utilities/hooks/components over large rewrites.
+- Do not extract a shared module without at least three call sites.
 - Preserve existing external behavior and route/store contracts.
 - Keep diffs reviewable with minimal unrelated formatting churn.
 - Add or update lightweight comments only when logic is non-obvious.