@starci/skills 1.1.0

package/knowledge/patterns/fe/imports.md

@@ -0,0 +1,87 @@
+# Imports
+
+This file answers one question: given a frontend file, what may it import, through which path,
+and in which order?
+
+Sources: `tsconfig.json` (`paths`), `eslint.config.mjs`, `src/hooks/index.ts`,
+`src/components/**`, `src/hooks/swr/**`.
+
+## FE-IMPORTS-1 — Paths
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Anything under `src/` from another folder | `@/…` — the only alias (`"@/*": ["./src/*"]`); 459 files use it |
+| Case 2 | A Grammar object | `import { SurfaceCard, Text, Heading, Badge, Button } from "@starci/grammar/common"` (553 imports, all through `/common`) |
+| Case 3 | HeroUI | `import { cn } from "@heroui/react"` in `classNames.ts` (136 of 151); vendor components in leaves (48) and blocks (74); page `component.tsx` never (0/49) |
+| Case 4 | Files inside the same unit | `./component`, `./classNames`, `./index` |
+| Case 5 | Type only | `import type { AuthMode } from "@/hooks/auth/useAuthPanel"`, `import { type CourseDetail } from "…"` (274 files) |
+
+## FE-IMPORTS-2 — Order
+
+Not lint-enforced (no `import/order` rule is configured). The dominant order, read from the first
+import of 417 component files, is framework, then Grammar, then own tiers, then own unit.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Framework first | `react` (108 files), `next-intl` (45), `next` / `next/navigation` (16), `swr` |
+| Case 2 | Then Grammar | `@starci/grammar/common` (95 files start here when no framework import exists) |
+| Case 3 | Then own tiers | `@/components/branches/…`, `@/components/leaves/…`, `@/hooks`, `@/modules/…` (88 files start with `@/components`) |
+| Case 4 | Own unit last | `import { aiChatClassNames, getAiChatBubbleClassName } from "./classNames"`, `import { AuthenticationPageBase } from "./component"` |
+
+`blocks/ai/StarCiAiChat/component.tsx` interleaves `@starci/grammar/common` and `@/components/…`
+imports alphabetically by binding instead; the order above is dominant, not universal.
+
+## FE-IMPORTS-3 — Data enters a block through the hooks barrel
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A block reads or writes | `import { useQueryCourseSwr } from "@/hooks"` (82 block files import `@/hooks`); the barrel docblock: "A block imports `@/hooks`, never `@/hooks/swr/useQuerySomethingSwr`" |
+| Case 2 | A hook reaches the transport | `import { queryCourse } from "../../modules/api/graphql/queries/query-course"` (57 hook files) or `from "@/modules/api/…"` (56 hook files) — evenly split, see open question |
+| Case 3 | A type from the data layer | `import type { CourseAdvisorRecommendation } from "@/modules/ai/course-advisor-response"` — types are not re-exported by the barrel |
+| Case 4 | Auth identity | `import { useViewerKey } from "@/hooks/auth/useViewerKey"` inside hooks; components mock `@/hooks/auth/useSessionToken` in specs |
+
+## FE-IMPORTS-4 — Tier direction
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Page → block | `import { AuthenticationPanel } from "@/components/blocks/auth/AuthenticationPanel"` (48 of 50 pages import blocks; 11 import leaves; 8 import hooks; 1 imports modules) |
+| Case 2 | Block → leaf, branch, Grammar, hooks, modules | `import { CodeBlock } from "@/components/leaves/CodeBlock"`, `import { Article } from "@/components/branches/Article"` (82 blocks import hooks, 67 import modules) |
+| Case 3 | Leaf → Grammar and vendor only | `import type { ButtonVariant } from "@starci/grammar/common"`, `import { buttonVariants } from "@heroui/styles"` (1 leaf imports hooks, 1 imports a block: outliers) |
+| Case 4 | Upward import | block → page observed once; leaf → block observed once; neither is a pattern |
+| Case 5 | Pure half → data layer | never at runtime; 18 `component.tsx` files use `import type` from `@/modules/api/graphql/queries/…` only |
+
+## FE-IMPORTS-5 — Vendor boundaries
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Glyphs | only the Icon leaf imports `@heroicons/react` (1 component file); everything else takes the Grammar `Icon` with a source prop (lint `no-vendor-icon-outside-icon-leaf`, `heroicons-is-the-glyph-vendor`) |
+| Case 2 | Headings | `Heading` from Grammar, never a raw `<h2>` (lint `no-heading-tag-outside-heading-component`) |
+| Case 3 | Grammar package dependencies | `peerDependencies` are exactly `@heroui/react` and `react`; `dependencies` is empty (`package-boundary.test.mjs`) |
+
+## FE-IMPORTS-6 — Re-exports
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | The hooks barrel | `export { useMutateAddToCartSwr } from "./swr/useMutateAddToCartSwr"` — one line per hook, no `export *` |
+| Case 2 | Grammar family entry | `export { COMMON_SPACING_SCALE, COMMON_SPACING_TOKENS, type CommonSpacingStep, … } from "./spacing.js"` — named, with `.js` suffix |
+| Case 3 | Block index re-exporting its twin | `export * from "./component"` at the end of `index.tsx` — 19 of 95 block indexes and 19 of 49 page indexes do this; the majority do not |
+
+## FE-IMPORTS-7 — Forbidden
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Deep hook path from a component | `@/hooks/swr/useQueryCourseSwr` — escapes `vi.mock("@/hooks")` |
+| Case 2 | Default export from `src/components` | 0 exist |
+| Case 3 | Inline lint config | `eslint-disable` appears in 0 files; `src/components/blocks/**/{index,component}.tsx` run with `noInlineConfig: true` |
+| Case 4 | `namespace` | only `src/modules/api/graphql/clients/options.ts`, by config exception |
+| Case 5 | Mixing families, or importing the package root | renderers and prop types come from the family entry `@starci/grammar/core` (which re-exports every Common renderer since 0.4.2) or from `@starci/grammar/common`; never from the package root, never from two families in one app |
+| Case 6 | A second family stylesheet under one root | one `CoreGrammarRoot` at the composition root, one `@starci/grammar/core/styles.css`; the family is selected once |
+| Case 7 | An app-local clone of a Common renderer or an anonymous layout | `TextLink`, `NavLink`, `SeeMoreLink`, a local `Sidebar` or shell geometry: use the Common renderer and pass props; a product adapter such as `LearnShellLayout` maps routes and state into Common, it owns no geometry |
+| Case 8 | A product name in a Grammar public export, or business logic inside Common/Core | `Learn`, `Console`, `Dashboard` stay in product code; routes, permissions, persistence and effects never enter the package |
+
+## Open questions
+
+- Hooks reach `modules/api` through `../../modules/api/…` in 57 files and `@/modules/api/…` in 56.
+  No variant dominates; this file does not choose.
+- `export * from "./component"` at the end of a connected `index.tsx` is present in 19/95 blocks
+  and absent in the rest. Not legislated.

package/knowledge/patterns/fe/imports.vi.md

@@ -0,0 +1,87 @@
+# Import
+
+Tệp này trả lời một câu hỏi: cho một tệp frontend, nó được import gì, qua đường dẫn nào, và theo
+thứ tự nào?
+
+Nguồn: `tsconfig.json` (`paths`), `eslint.config.mjs`, `src/hooks/index.ts`,
+`src/components/**`, `src/hooks/swr/**`.
+
+## FE-IMPORTS-1 — Đường dẫn
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Bất cứ thứ gì dưới `src/` từ thư mục khác | `@/…` — alias duy nhất (`"@/*": ["./src/*"]`); 459 tệp dùng nó |
+| Case 2 | Một đối tượng Grammar | `import { SurfaceCard, Text, Heading, Badge, Button } from "@starci/grammar/common"` (553 import, tất cả qua `/common`) |
+| Case 3 | HeroUI | `import { cn } from "@heroui/react"` trong `classNames.ts` (136 trên 151); component nhà cung cấp trong leaf (48) và block (74); `component.tsx` của page không bao giờ (0/49) |
+| Case 4 | Tệp trong cùng đơn vị | `./component`, `./classNames`, `./index` |
+| Case 5 | Chỉ kiểu | `import type { AuthMode } from "@/hooks/auth/useAuthPanel"`, `import { type CourseDetail } from "…"` (274 tệp) |
+
+## FE-IMPORTS-2 — Thứ tự
+
+Không bị lint ép (không cấu hình luật `import/order`). Thứ tự chiếm ưu thế, đọc từ import đầu tiên
+của 417 tệp component, là framework, rồi Grammar, rồi tầng của mình, rồi đơn vị của mình.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Framework trước | `react` (108 tệp), `next-intl` (45), `next` / `next/navigation` (16), `swr` |
+| Case 2 | Rồi Grammar | `@starci/grammar/common` (95 tệp bắt đầu ở đây khi không có import framework) |
+| Case 3 | Rồi tầng của mình | `@/components/branches/…`, `@/components/leaves/…`, `@/hooks`, `@/modules/…` (88 tệp bắt đầu bằng `@/components`) |
+| Case 4 | Đơn vị của mình sau cùng | `import { aiChatClassNames, getAiChatBubbleClassName } from "./classNames"`, `import { AuthenticationPageBase } from "./component"` |
+
+`blocks/ai/StarCiAiChat/component.tsx` lại xen kẽ import `@starci/grammar/common` và
+`@/components/…` theo thứ tự chữ cái của tên binding; thứ tự trên là ưu thế, không phải toàn thể.
+
+## FE-IMPORTS-3 — Dữ liệu vào block qua barrel hooks
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Block đọc hoặc ghi | `import { useQueryCourseSwr } from "@/hooks"` (82 tệp block import `@/hooks`); docblock của barrel nói rõ block import `@/hooks`, không bao giờ `@/hooks/swr/useQuerySomethingSwr` |
+| Case 2 | Hook chạm tới tầng vận chuyển | `import { queryCourse } from "../../modules/api/graphql/queries/query-course"` (57 tệp hook) hoặc `from "@/modules/api/…"` (56 tệp hook) — chia đều, xem câu hỏi để ngỏ |
+| Case 3 | Một kiểu từ tầng dữ liệu | `import type { CourseAdvisorRecommendation } from "@/modules/ai/course-advisor-response"` — barrel không re-export kiểu |
+| Case 4 | Danh tính xác thực | `import { useViewerKey } from "@/hooks/auth/useViewerKey"` bên trong hook; component giả lập `@/hooks/auth/useSessionToken` trong spec |
+
+## FE-IMPORTS-4 — Chiều giữa các tầng
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Page → block | `import { AuthenticationPanel } from "@/components/blocks/auth/AuthenticationPanel"` (48 trên 50 page import block; 11 import leaf; 8 import hooks; 1 import modules) |
+| Case 2 | Block → leaf, branch, Grammar, hooks, modules | `import { CodeBlock } from "@/components/leaves/CodeBlock"`, `import { Article } from "@/components/branches/Article"` (82 block import hooks, 67 import modules) |
+| Case 3 | Leaf → chỉ Grammar và nhà cung cấp | `import type { ButtonVariant } from "@starci/grammar/common"`, `import { buttonVariants } from "@heroui/styles"` (1 leaf import hooks, 1 import block: ngoại lệ) |
+| Case 4 | Import ngược lên | block → page thấy một lần; leaf → block thấy một lần; không cái nào là mẫu |
+| Case 5 | Nửa thuần → tầng dữ liệu | không bao giờ lúc chạy; 18 tệp `component.tsx` chỉ dùng `import type` từ `@/modules/api/graphql/queries/…` |
+
+## FE-IMPORTS-5 — Ranh giới nhà cung cấp
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Ký tự biểu tượng | chỉ leaf Icon import `@heroicons/react` (1 tệp component); mọi nơi khác nhận `Icon` của Grammar với một prop nguồn (lint `no-vendor-icon-outside-icon-leaf`, `heroicons-is-the-glyph-vendor`) |
+| Case 2 | Tiêu đề | `Heading` từ Grammar, không bao giờ `<h2>` trần (lint `no-heading-tag-outside-heading-component`) |
+| Case 3 | Phụ thuộc của gói Grammar | `peerDependencies` đúng là `@heroui/react` và `react`; `dependencies` rỗng (`package-boundary.test.mjs`) |
+
+## FE-IMPORTS-6 — Re-export
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Barrel hooks | `export { useMutateAddToCartSwr } from "./swr/useMutateAddToCartSwr"` — một dòng cho mỗi hook, không `export *` |
+| Case 2 | Cửa vào họ Grammar | `export { COMMON_SPACING_SCALE, COMMON_SPACING_TOKENS, type CommonSpacingStep, … } from "./spacing.js"` — có tên, kèm hậu tố `.js` |
+| Case 3 | Index của block re-export bản sao | `export * from "./component"` ở cuối `index.tsx` — 19 trên 95 index block và 19 trên 49 index page làm vậy; đa số không |
+
+## FE-IMPORTS-7 — Bị cấm
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Đường dẫn sâu tới hook từ component | `@/hooks/swr/useQueryCourseSwr` — thoát khỏi `vi.mock("@/hooks")` |
+| Case 2 | Default export trong `src/components` | 0 tồn tại |
+| Case 3 | Cấu hình lint nội tuyến | `eslint-disable` xuất hiện trong 0 tệp; `src/components/blocks/**/{index,component}.tsx` chạy với `noInlineConfig: true` |
+| Case 4 | `namespace` | chỉ `src/modules/api/graphql/clients/options.ts`, theo ngoại lệ ghi trong cấu hình |
+| Case 5 | Trộn family, hay import từ gốc gói | renderer và kiểu props lấy từ entry family `@starci/grammar/core` (từ 0.4.2 re-export toàn bộ renderer của Common) hoặc từ `@starci/grammar/common`; không bao giờ từ gốc gói, không bao giờ hai family trong một app |
+| Case 6 | Stylesheet của family thứ hai dưới cùng một root | một `CoreGrammarRoot` ở root của composition, một `@starci/grammar/core/styles.css`; family được chọn đúng một lần |
+| Case 7 | Bản sao cục bộ của một renderer Common hay một layout vô danh | `TextLink`, `NavLink`, `SeeMoreLink`, `Sidebar` hay hình học shell tự dựng: dùng renderer của Common và truyền prop; adapter sản phẩm như `LearnShellLayout` chỉ ánh xạ route và state vào Common, không sở hữu hình học |
+| Case 8 | Tên sản phẩm trong export công khai của Grammar, hay logic nghiệp vụ bên trong Common/Core | `Learn`, `Console`, `Dashboard` ở lại code sản phẩm; route, quyền, persistence và effect không bao giờ vào gói |
+
+## Câu hỏi để ngỏ
+
+- Hook chạm tới `modules/api` qua `../../modules/api/…` ở 57 tệp và `@/modules/api/…` ở 56 tệp.
+  Không biến thể nào chiếm ưu thế; tệp này không chọn.
+- `export * from "./component"` ở cuối `index.tsx` nối dữ liệu có ở 19/95 block và vắng ở phần còn
+  lại. Không áp đặt.

package/knowledge/patterns/fe/naming.md

@@ -0,0 +1,77 @@
+# Naming
+
+This file answers one question: given a folder, export, type, constant or function in the
+frontend, what is it called?
+
+Sources: `src/components/pages/*`, `src/components/blocks/*/*`, `src/components/leaves/*`,
+`src/hooks/swr/*`, `src/modules/api/graphql/**`.
+
+## FE-NAMING-1 — Unit folder and its two exports
+
+The folder name is the connected export; the pure twin appends `Base`.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Page connected half, `pages/CartPage/index.tsx` | `export const CartPage = (props: CartPageProps) => …` (49/49 pages) |
+| Case 2 | Page pure half, `pages/AuthenticationPage/component.tsx` | `export const AuthenticationPageBase = (props: AuthenticationPageProps) => …` (47/49; the two `CoursePlayground*Page` units export `…PageShell`) |
+| Case 3 | Block pure half, `blocks/ai/StarCiAiChat/component.tsx` | `export const StarCiAiChatBase = …` (98 of 118 `component.tsx` exports end in `Base`) |
+| Case 4 | Leaf, `leaves/ButtonStateSample/index.tsx` | `export const ButtonStateSample = …` — no `Base`, no twin |
+| Case 5 | Route wrapper, `app/[lang]/authentication/page.tsx` | `const AuthenticationRoute = () => …` |
+
+## FE-NAMING-2 — Props and its parts
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | The props type | `export type StarCiAiChatProps = { … }` (403 `export type …Props` against 6 `export interface …Props`) |
+| Case 2 | Resolved facts | `export type StarCiAiChatData = { … }`, `export type ButtonStateSampleData = { … }` |
+| Case 3 | Resolved copy | `export type StarCiAiChatLabels = { … }`, `CourseAdvisorRecommendationCardLabels` |
+| Case 4 | Handlers | `export type StarCiAiChatActions = { … }`, `AuthenticationPageActions` |
+| Case 5 | State inventory | `export type StarCiAiChatState = "sessionsPending" \| …`; `export type StarCiAiMode = "general" \| "history"` |
+| Case 6 | The same name in both halves | `AuthenticationPageProps` is declared in `component.tsx` and again in `index.tsx` with a different shape; each file owns its own `XProps` |
+
+## FE-NAMING-3 — Class-name exports
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | One string for one role | `export const authenticationPageClassName = cn(formPageClassName)` (931 `…ClassName` exports) |
+| Case 2 | A map of roles for one unit | `export const aiChatClassNames = { root: cn(…), intro: cn(…), … } as const` (9 `…ClassNames` exports; 7 of 151 `classNames.ts` files use the object form) |
+| Case 3 | A variant resolved at call time | `export const getAiChatBubbleClassName = (role: "user" \| "assistant") => …`; `export const getButtonStateSampleClassName = (variant: …) => buttonVariants({ variant, size: "sm" })` |
+| Case 4 | Grammar package | `export const railClassName`, `railFrameClassName`, `railBodyClassName`, `railFooterClassName` (`core/branch/Rail/classNames.ts`) |
+
+## FE-NAMING-4 — Hooks and keys
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Read hook | `useQueryCourseSwr`, `useQueryMyCartSwr` (80 files `useQuery…Swr.ts`) |
+| Case 2 | Write hook | `useMutateAddToCartSwr`, `useMutateClearCartSwr` (32 files `useMutate…Swr.ts`) |
+| Case 3 | Key constant | `export const QUERY_COURSE_SWR_KEY = "QUERY_COURSE_SWR"`, `export const MUTATE_ADD_TO_CART_SWR_KEY = "MUTATE_ADD_TO_CART_SWR"` |
+| Case 4 | Hook params type | `export interface UseQueryCourseSwrParams { displayId?: string }`; trigger arg `export type AddToCartArg`, `export type AddToCartTrigger` |
+| Case 5 | Non-data hooks | `useSessionToken`, `useViewerKey`, `useAuthPanel` under `hooks/auth/` |
+| Case 6 | GraphQL document module | `modules/api/graphql/queries/query-course.ts`, `mutations/mutation-add-to-cart.ts`; the document const is `query1`, the function `queryCourse` / `mutationAddToCart` |
+
+## FE-NAMING-5 — Constants and module-level values
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Frozen module value | `const HISTORY_STATES = new Set<StarCiAiChatState>([…])`, `const PENDING_TURN_IDS = ["pending-1", "pending-2"] as const`, `const DEFAULT_MESSAGES: ToastMessages = { … }` (120 exported + 163 local `UPPER_SNAKE` consts) |
+| Case 2 | Exported inventory | `export const STARCI_AI_CHAT_STATES: ReadonlyArray<StarCiAiChatState> = […]` |
+| Case 3 | Grammar lookup tables | `const VARIANTS = { primary: "primary", … } as const`, `const SIZES = { sm: "sm", md: "md", lg: "lg" } as const`, `const SKELETON_CLASS_NAME = …` (`core/primitive/Button/index.tsx`) |
+| Case 4 | Operation-name enums (the only enums in `src/`) | `export enum MutationCvBlocks { Create = "create", Update = "update", Render = "render", Rewrite = "rewrite" }` (92, all in `modules/api/graphql`) |
+
+## FE-NAMING-6 — Handlers, booleans, helpers
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Action handler | bare verb inside the `on` object: `on?: { signedIn?: () => void }`, `on?.send`, `on?.selectMode?.("general")` — never `onX` on the pure half (lint `handler-on-prefix`) |
+| Case 2 | Boolean prop | `is`/`has` prefix: `isLoading`, `isEnrolled`, `isPartial`, `isArchived`, `isOnline` (286 of 366 boolean props) |
+| Case 3 | Local pure helper | verb or noun phrase in camelCase: `stateNeedsRetry`, `turnMarkdown`, `routeState` |
+| Case 4 | Local sub-render | PascalCase with its own props type: `const Turn = (props: TurnProps) => …` |
+
+## FE-NAMING-7 — File names outside component folders
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Hook file | camelCase equal to the export: `useQueryCourseSwr.ts`, `useSessionToken.ts` |
+| Case 2 | Module file | kebab-case: `query-course.ts`, `course-advisor-response.ts`, `content-ai-selection-context.ts`, `create-apollo-client.ts` |
+| Case 3 | Spec file | same basename plus `.spec`: `useQueryCourseSwr.spec.ts`, `component.spec.tsx`, `index.spec.tsx` |
+| Case 4 | Spec `describe` | the export name: `describe("StarCiAiChatBase"` in `component.spec.tsx` (85/97), `describe("CartBlock"` in `index.spec.tsx` (0 `…Base` there) |

package/knowledge/patterns/fe/naming.vi.md

@@ -0,0 +1,77 @@
+# Đặt tên
+
+Tệp này trả lời một câu hỏi: cho một thư mục, export, kiểu, hằng hay hàm trong frontend, nó được
+gọi là gì?
+
+Nguồn: `src/components/pages/*`, `src/components/blocks/*/*`, `src/components/leaves/*`,
+`src/hooks/swr/*`, `src/modules/api/graphql/**`.
+
+## FE-NAMING-1 — Thư mục đơn vị và hai export của nó
+
+Tên thư mục là export nối dữ liệu; bản sao thuần thêm hậu tố `Base`.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Nửa nối của page, `pages/CartPage/index.tsx` | `export const CartPage = (props: CartPageProps) => …` (49/49 page) |
+| Case 2 | Nửa thuần của page, `pages/AuthenticationPage/component.tsx` | `export const AuthenticationPageBase = (props: AuthenticationPageProps) => …` (47/49; hai đơn vị `CoursePlayground*Page` export `…PageShell`) |
+| Case 3 | Nửa thuần của block, `blocks/ai/StarCiAiChat/component.tsx` | `export const StarCiAiChatBase = …` (98 trên 118 export trong `component.tsx` kết thúc bằng `Base`) |
+| Case 4 | Leaf, `leaves/ButtonStateSample/index.tsx` | `export const ButtonStateSample = …` — không `Base`, không bản sao |
+| Case 5 | Vỏ route, `app/[lang]/authentication/page.tsx` | `const AuthenticationRoute = () => …` |
+
+## FE-NAMING-2 — Props và các phần của nó
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Kiểu props | `export type StarCiAiChatProps = { … }` (403 `export type …Props` so với 6 `export interface …Props`) |
+| Case 2 | Dữ kiện đã giải | `export type StarCiAiChatData = { … }`, `export type ButtonStateSampleData = { … }` |
+| Case 3 | Câu chữ đã giải | `export type StarCiAiChatLabels = { … }`, `CourseAdvisorRecommendationCardLabels` |
+| Case 4 | Bộ xử lý | `export type StarCiAiChatActions = { … }`, `AuthenticationPageActions` |
+| Case 5 | Kho trạng thái | `export type StarCiAiChatState = "sessionsPending" \| …`; `export type StarCiAiMode = "general" \| "history"` |
+| Case 6 | Cùng tên ở cả hai nửa | `AuthenticationPageProps` được khai báo trong `component.tsx` và khai báo lại trong `index.tsx` với hình dạng khác; mỗi tệp sở hữu `XProps` của riêng nó |
+
+## FE-NAMING-3 — Export class-name
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một chuỗi cho một vai trò | `export const authenticationPageClassName = cn(formPageClassName)` (931 export `…ClassName`) |
+| Case 2 | Một bản đồ vai trò cho một đơn vị | `export const aiChatClassNames = { root: cn(…), intro: cn(…), … } as const` (9 export `…ClassNames`; 7 trên 151 tệp `classNames.ts` dùng dạng object) |
+| Case 3 | Biến thể giải lúc gọi | `export const getAiChatBubbleClassName = (role: "user" \| "assistant") => …`; `export const getButtonStateSampleClassName = (variant: …) => buttonVariants({ variant, size: "sm" })` |
+| Case 4 | Gói Grammar | `export const railClassName`, `railFrameClassName`, `railBodyClassName`, `railFooterClassName` (`core/branch/Rail/classNames.ts`) |
+
+## FE-NAMING-4 — Hook và khóa
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Hook đọc | `useQueryCourseSwr`, `useQueryMyCartSwr` (80 tệp `useQuery…Swr.ts`) |
+| Case 2 | Hook ghi | `useMutateAddToCartSwr`, `useMutateClearCartSwr` (32 tệp `useMutate…Swr.ts`) |
+| Case 3 | Hằng khóa | `export const QUERY_COURSE_SWR_KEY = "QUERY_COURSE_SWR"`, `export const MUTATE_ADD_TO_CART_SWR_KEY = "MUTATE_ADD_TO_CART_SWR"` |
+| Case 4 | Kiểu tham số hook | `export interface UseQueryCourseSwrParams { displayId?: string }`; đối số trigger `export type AddToCartArg`, `export type AddToCartTrigger` |
+| Case 5 | Hook không phải dữ liệu | `useSessionToken`, `useViewerKey`, `useAuthPanel` dưới `hooks/auth/` |
+| Case 6 | Module tài liệu GraphQL | `modules/api/graphql/queries/query-course.ts`, `mutations/mutation-add-to-cart.ts`; hằng tài liệu là `query1`, hàm là `queryCourse` / `mutationAddToCart` |
+
+## FE-NAMING-5 — Hằng và giá trị cấp module
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Giá trị module đóng băng | `const HISTORY_STATES = new Set<StarCiAiChatState>([…])`, `const PENDING_TURN_IDS = ["pending-1", "pending-2"] as const`, `const DEFAULT_MESSAGES: ToastMessages = { … }` (120 hằng `UPPER_SNAKE` export + 163 cục bộ) |
+| Case 2 | Kho export | `export const STARCI_AI_CHAT_STATES: ReadonlyArray<StarCiAiChatState> = […]` |
+| Case 3 | Bảng tra trong Grammar | `const VARIANTS = { primary: "primary", … } as const`, `const SIZES = { sm: "sm", md: "md", lg: "lg" } as const`, `const SKELETON_CLASS_NAME = …` (`core/primitive/Button/index.tsx`) |
+| Case 4 | Enum tên thao tác (enum duy nhất trong `src/`) | `export enum MutationCvBlocks { Create = "create", Update = "update", Render = "render", Rewrite = "rewrite" }` (92, toàn bộ trong `modules/api/graphql`) |
+
+## FE-NAMING-6 — Bộ xử lý, boolean, helper
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Bộ xử lý hành động | động từ trần trong object `on`: `on?: { signedIn?: () => void }`, `on?.send`, `on?.selectMode?.("general")` — không bao giờ `onX` ở nửa thuần (lint `handler-on-prefix`) |
+| Case 2 | Prop boolean | tiền tố `is`/`has`: `isLoading`, `isEnrolled`, `isPartial`, `isArchived`, `isOnline` (286 trên 366 prop boolean) |
+| Case 3 | Helper thuần cục bộ | cụm động từ hoặc danh từ camelCase: `stateNeedsRetry`, `turnMarkdown`, `routeState` |
+| Case 4 | Bộ vẽ con cục bộ | PascalCase với kiểu props riêng: `const Turn = (props: TurnProps) => …` |
+
+## FE-NAMING-7 — Tên tệp ngoài thư mục component
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Tệp hook | camelCase trùng export: `useQueryCourseSwr.ts`, `useSessionToken.ts` |
+| Case 2 | Tệp module | kebab-case: `query-course.ts`, `course-advisor-response.ts`, `content-ai-selection-context.ts`, `create-apollo-client.ts` |
+| Case 3 | Tệp spec | cùng tên gốc cộng `.spec`: `useQueryCourseSwr.spec.ts`, `component.spec.tsx`, `index.spec.tsx` |
+| Case 4 | `describe` trong spec | tên export: `describe("StarCiAiChatBase"` trong `component.spec.tsx` (85/97), `describe("CartBlock"` trong `index.spec.tsx` (0 `…Base` ở đó) |

package/knowledge/patterns/fe/test.md

@@ -0,0 +1,73 @@
+# Test
+
+This file answers one question: given a frontend unit, where does its spec live, what does it
+assert, and what does it leave alone?
+
+Sources: `src/components/pages/CartPage/index.spec.tsx`,
+`pages/CodingDomainPage/component.spec.tsx`, `blocks/commerce/CartBlock/index.spec.tsx`,
+`hooks/index.ts`, `packages/grammar/src/**/*.spec.tsx`, `packages/grammar/src/**/*.test.mjs`,
+`package.json` scripts (`vitest run`).
+
+## FE-TEST-1 — Placement
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Pure half | `component.spec.tsx` beside `component.tsx` (55 blocks, 42 pages) |
+| Case 2 | Connected half | `index.spec.tsx` beside `index.tsx` (61 blocks, 24 pages, 19 leaves) |
+| Case 3 | Hook | `useQueryCourseSwr.spec.ts` beside the hook |
+| Case 4 | Class strings | `classNames.spec.ts` beside `classNames.ts` (2 in blocks); Grammar CSS proof in `styles.spec.ts` (6) |
+| Case 5 | Anywhere else | 0 of 497 specs live in a `__tests__/` folder |
+| Case 6 | Runner | `vitest`, `@testing-library/react`; `describe/it/expect/vi` imported from `"vitest"` |
+
+## FE-TEST-2 — Connected spec: mock the doors, assert the props handed down
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Hoisted mock state | `const mocks = vi.hoisted(() => ({ input: undefined as TestInput \| undefined, token: "token" as string \| undefined, cart: { data: undefined as unknown, error: undefined as unknown, isLoading: false, mutate: vi.fn() }, … }))` |
+| Case 2 | The hooks barrel | `vi.mock("@/hooks", () => ({ useQueryMyCartSwr: () => mocks.cart, useQueryCoursesCheckoutPreviewSwr: () => mocks.preview, … }))` (25 of 61 block index specs) |
+| Case 3 | Translation and routing | `vi.mock("next-intl", () => ({ useLocale: () => "en", useTranslations: () => (key: string) => key }))`, `vi.mock("@/i18n/navigation", () => ({ useRouter: () => ({ push: mocks.push }) }))` |
+| Case 4 | The pure twin | `vi.mock("./component", () => ({ CartBlockBase: (input: TestInput) => { mocks.input = input; return <output data-testid="cart" /> } }))` |
+| Case 5 | Import after mocks | `import { CartBlock } from "./index"` placed after the `vi.mock` calls |
+| Case 6 | Assertion | `expect(mocks.input?.blockState).toBe("empty")`, `act(() => { mocks.input?.on.pay() })`, `expect(mocks.checkout.trigger).toHaveBeenCalledWith(expect.objectContaining({ paymentType: "payos" }))` |
+| Case 7 | Reset | `beforeEach(() => { vi.clearAllMocks(); mocks.input = undefined; … })` |
+
+## FE-TEST-3 — Pure spec: render fixtures, assert what a reader would find
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Render | `render(<CodingDomainPageBase domain="arrays" navHome="Home" navPractice="Practice" title="Arrays" />)` |
+| Case 2 | Landmarks and text | `expect(screen.getByRole("heading", { name: "Arrays" })).toBeInTheDocument()` (185 specs use `getByRole`, 173 `getByText`, 60 `getByTestId`) |
+| Case 3 | Child owners stubbed | `vi.mock("@/components/blocks/coding/CodingDomainStanding", () => ({ CodingDomainStanding: () => <div data-testid="domain-standing" /> }))` then `expect(screen.getByTestId("domain-standing")).toBeInTheDocument()` |
+| Case 4 | Page composes without owning | `it("composes the connected cart block without owning its state", () => { render(<CartPage />); expect(screen.getByTestId("cart-block")).toHaveTextContent("cart-block") })` |
+| Case 5 | State inventory | pure specs iterate the exported `X_STATES` array to render every member |
+
+## FE-TEST-4 — Names
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | `describe` | the export under test: `describe("CodingDomainPageBase"`, `describe("CartBlock"`, `describe("CartPage route"` (85 of 97 `component.spec` use the `…Base` name; 0 `index.spec` do) |
+| Case 2 | `it` | a sentence about behaviour: `"keeps topic anatomy while composing connected standing and problem owners"`, `"maps cart states and dispatches browse, clear and checkout actions"` |
+
+## FE-TEST-5 — Not asserted
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Snapshots | 0 `toMatchSnapshot` / `toMatchInlineSnapshot` in `src/` |
+| Case 2 | Network | never reached; `@/hooks` is mocked wholesale, which is why the barrel exists |
+| Case 3 | Translation content | `useTranslations: () => (key: string) => key` — a spec asserts keys, not copy |
+| Case 4 | Class strings in a component spec | dominant practice is not to; see open question |
+
+## FE-TEST-6 — Grammar package
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Component behaviour | `index.spec.tsx` beside `index.tsx` (24) |
+| Case 2 | Built output | `common/index.test.mjs`: `import test from "node:test"` … `assert.equal(COMMON_UI_RULE_IDS.length, 117)` against `../../dist/common/index.js` |
+| Case 3 | Package surface | `package-boundary.test.mjs`: `assert.deepEqual(Object.keys(packageJson.peerDependencies).sort(), ["@heroui/react", "react"])` |
+| Case 4 | Family-wide proof | `core/family.spec.tsx`, `core/surface-card-family.spec.tsx`, `core/scrollable-surfaces.spec.tsx` |
+
+## Open question
+
+64 of 272 component specs contain `toHaveClass` or `className`. The other 208 assert roles, text
+and handed-down props only, and class proof has dedicated homes (`classNames.spec.ts`,
+`styles.spec.ts`). The majority practice is recorded; the 64 are not declared wrong here.

package/knowledge/patterns/fe/test.vi.md

@@ -0,0 +1,73 @@
+# Kiểm thử
+
+Tệp này trả lời một câu hỏi: cho một đơn vị frontend, spec của nó nằm đâu, khẳng định gì, và
+để yên điều gì?
+
+Nguồn: `src/components/pages/CartPage/index.spec.tsx`,
+`pages/CodingDomainPage/component.spec.tsx`, `blocks/commerce/CartBlock/index.spec.tsx`,
+`hooks/index.ts`, `packages/grammar/src/**/*.spec.tsx`, `packages/grammar/src/**/*.test.mjs`,
+script trong `package.json` (`vitest run`).
+
+## FE-TEST-1 — Vị trí
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Nửa thuần | `component.spec.tsx` cạnh `component.tsx` (55 block, 42 page) |
+| Case 2 | Nửa nối | `index.spec.tsx` cạnh `index.tsx` (61 block, 24 page, 19 leaf) |
+| Case 3 | Hook | `useQueryCourseSwr.spec.ts` cạnh hook |
+| Case 4 | Chuỗi class | `classNames.spec.ts` cạnh `classNames.ts` (2 trong block); chứng minh CSS của Grammar trong `styles.spec.ts` (6) |
+| Case 5 | Nơi khác | 0 trên 497 spec nằm trong thư mục `__tests__/` |
+| Case 6 | Bộ chạy | `vitest`, `@testing-library/react`; `describe/it/expect/vi` import từ `"vitest"` |
+
+## FE-TEST-2 — Spec nửa nối: giả lập các cánh cửa, khẳng định props được trao xuống
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | State giả lập được hoist | `const mocks = vi.hoisted(() => ({ input: undefined as TestInput \| undefined, token: "token" as string \| undefined, cart: { data: undefined as unknown, error: undefined as unknown, isLoading: false, mutate: vi.fn() }, … }))` |
+| Case 2 | Barrel hooks | `vi.mock("@/hooks", () => ({ useQueryMyCartSwr: () => mocks.cart, useQueryCoursesCheckoutPreviewSwr: () => mocks.preview, … }))` (25 trên 61 spec index của block) |
+| Case 3 | Dịch và điều hướng | `vi.mock("next-intl", () => ({ useLocale: () => "en", useTranslations: () => (key: string) => key }))`, `vi.mock("@/i18n/navigation", () => ({ useRouter: () => ({ push: mocks.push }) }))` |
+| Case 4 | Bản sao thuần | `vi.mock("./component", () => ({ CartBlockBase: (input: TestInput) => { mocks.input = input; return <output data-testid="cart" /> } }))` |
+| Case 5 | Import sau các mock | `import { CartBlock } from "./index"` đặt sau các lời gọi `vi.mock` |
+| Case 6 | Khẳng định | `expect(mocks.input?.blockState).toBe("empty")`, `act(() => { mocks.input?.on.pay() })`, `expect(mocks.checkout.trigger).toHaveBeenCalledWith(expect.objectContaining({ paymentType: "payos" }))` |
+| Case 7 | Đặt lại | `beforeEach(() => { vi.clearAllMocks(); mocks.input = undefined; … })` |
+
+## FE-TEST-3 — Spec nửa thuần: vẽ fixture, khẳng định điều người đọc sẽ tìm thấy
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Vẽ | `render(<CodingDomainPageBase domain="arrays" navHome="Home" navPractice="Practice" title="Arrays" />)` |
+| Case 2 | Mốc và chữ | `expect(screen.getByRole("heading", { name: "Arrays" })).toBeInTheDocument()` (185 spec dùng `getByRole`, 173 `getByText`, 60 `getByTestId`) |
+| Case 3 | Chủ sở hữu con bị thay thế | `vi.mock("@/components/blocks/coding/CodingDomainStanding", () => ({ CodingDomainStanding: () => <div data-testid="domain-standing" /> }))` rồi `expect(screen.getByTestId("domain-standing")).toBeInTheDocument()` |
+| Case 4 | Page ghép mà không sở hữu | `it("composes the connected cart block without owning its state", () => { render(<CartPage />); expect(screen.getByTestId("cart-block")).toHaveTextContent("cart-block") })` |
+| Case 5 | Kho trạng thái | spec thuần lặp qua mảng `X_STATES` được export để vẽ từng thành viên |
+
+## FE-TEST-4 — Tên
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | `describe` | export đang được thử: `describe("CodingDomainPageBase"`, `describe("CartBlock"`, `describe("CartPage route"` (85 trên 97 `component.spec` dùng tên `…Base`; 0 `index.spec` dùng) |
+| Case 2 | `it` | một câu về hành vi: `"keeps topic anatomy while composing connected standing and problem owners"`, `"maps cart states and dispatches browse, clear and checkout actions"` |
+
+## FE-TEST-5 — Không khẳng định
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Snapshot | 0 `toMatchSnapshot` / `toMatchInlineSnapshot` trong `src/` |
+| Case 2 | Mạng | không bao giờ chạm tới; `@/hooks` bị giả lập toàn bộ, đó là lý do barrel tồn tại |
+| Case 3 | Nội dung bản dịch | `useTranslations: () => (key: string) => key` — spec khẳng định khóa, không khẳng định câu chữ |
+| Case 4 | Chuỗi class trong spec component | thực hành chiếm ưu thế là không; xem câu hỏi để ngỏ |
+
+## FE-TEST-6 — Gói Grammar
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Hành vi component | `index.spec.tsx` cạnh `index.tsx` (24) |
+| Case 2 | Bản build | `common/index.test.mjs`: `import test from "node:test"` … `assert.equal(COMMON_UI_RULE_IDS.length, 117)` chạy trên `../../dist/common/index.js` |
+| Case 3 | Bề mặt gói | `package-boundary.test.mjs`: `assert.deepEqual(Object.keys(packageJson.peerDependencies).sort(), ["@heroui/react", "react"])` |
+| Case 4 | Chứng minh toàn họ | `core/family.spec.tsx`, `core/surface-card-family.spec.tsx`, `core/scrollable-surfaces.spec.tsx` |
+
+## Câu hỏi để ngỏ
+
+64 trên 272 spec component chứa `toHaveClass` hoặc `className`. 208 spec còn lại chỉ khẳng định
+vai trò, chữ và props được trao xuống, còn chứng minh class đã có nhà riêng (`classNames.spec.ts`,
+`styles.spec.ts`). Thực hành đa số được ghi lại; 64 spec kia không bị tuyên là sai ở đây.

package/knowledge/patterns/fe/typing.md

@@ -0,0 +1,67 @@
+# Typing
+
+This file answers one question: given a frontend value, how is its type declared?
+
+Sources: `tsconfig.json` (`strict: true`), `eslint.config.mjs` (`@typescript-eslint/array-type`
+generic), `src/components/**`, `src/hooks/swr/*`, `src/modules/toast/api.ts`,
+`packages/grammar/src/common/conformance.ts`, `core/primitive/Button/index.tsx`.
+
+## FE-TYPING-1 — `type` for shapes, `interface` in the hook layer
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Props and data shapes | `export type StarCiAiTurn = { readonly id: string; readonly role: "user" \| "assistant"; … }` (919 `export type X = {` against 232 `export interface` in `src/`, 403 vs 6 for `…Props`) |
+| Case 2 | Hook params | `export interface UseQueryCourseSwrParams { displayId?: string }` — the `interface` share sits in `hooks/` and `modules/api`, not in components |
+| Case 3 | Intersection | `export type CourseAdvisorRecommendationCardData = CourseAdvisorRecommendation & { readonly title?: string; … }` |
+| Case 4 | Grammar package | `export type ButtonProps = { … }`, `export type GrammarRuleConformance = { … }` — `type` throughout |
+
+## FE-TYPING-2 — `readonly` on every field
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Props field | `readonly measure?: "form" \| "formCompact"` (2336 `readonly` prop lines against 69 without) |
+| Case 2 | Nested object | `readonly action: { readonly href: string; readonly label: string }` |
+| Case 3 | Collection | `readonly turns: ReadonlyArray<StarCiAiTurn>`, `readonly states: Readonly<Record<StarCiAiChatState, string>>` |
+| Case 4 | Tuple key | `_key: readonly [string, string]` |
+
+## FE-TYPING-3 — Literal unions, not booleans, for state
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Component state | `export type StarCiAiChatState = \| "sessionsPending" \| "sessionsFailed" \| "noSession" \| … \| "contextCleared"` (21 members) |
+| Case 2 | Mode | `export type StarCiAiMode = "general" \| "history"`; `role: "user" \| "assistant"` |
+| Case 3 | Inventory of the union | `export const STARCI_AI_CHAT_STATES: ReadonlyArray<StarCiAiChatState> = [ … ]` beside the type |
+| Case 4 | Flag that is truly binary | `readonly isLoading?: boolean`, `readonly isPartial?: boolean` — `is`/`has` prefixed |
+| Case 5 | Closed vocabulary in Grammar | `export type ButtonVariant = "primary" \| "secondary" \| "tertiary" \| "outline" \| "ghost"`; `const VARIANTS = { … } as const` |
+
+## FE-TYPING-4 — Arrays
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Any array type | `ReadonlyArray<string>`, `Array<T>` — never `T[]` (lint `@typescript-eslint/array-type: generic`) |
+| Case 2 | Frozen literal | `const PENDING_TURN_IDS = ["pending-1", "pending-2"] as const` (252 `as const` sites in `src/`) |
+
+## FE-TYPING-5 — Inferred and declared
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Component return | inferred; no `: JSX.Element` on any of the 441 components |
+| Case 2 | Helper return | declared when primitive: `(state: StarCiAiChatState): boolean =>`, `(turn: StarCiAiTurn, partialLabel: string): string =>` |
+| Case 3 | Hook return | inferred from `useSWR<CourseDetail \| null>(…)`; the generic names the data |
+| Case 4 | Async utility | declared: `export const runGraphQLWithToast = async <T>(action: () => Promise<GraphQLResponse<T>>, options: RunGraphQLWithToastOptions = {}): Promise<boolean>` |
+| Case 5 | Narrowed literal | `return { mode: "signIn" as const, step: "code" as const, measure: "form" as const }` so a switch returns a union, not `string` |
+
+## FE-TYPING-6 — Casting
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Double cast | not written (lint `no-double-cast`) |
+| Case 2 | Spec mock slot | `data: undefined as unknown` inside `vi.hoisted(() => ({ … }))` |
+| Case 3 | Ignoring a prop | `void props` rather than an underscore or a cast |
+
+## FE-TYPING-7 — Enums
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Component vocabulary | never an enum; a string-literal union |
+| Case 2 | GraphQL operation names | `export enum MutationCvBlocks { Create = "create", … }` — the 92 enums in `src/` are all in `modules/api/graphql` |

package/knowledge/patterns/fe/typing.vi.md

@@ -0,0 +1,67 @@
+# Kiểu
+
+Tệp này trả lời một câu hỏi: cho một giá trị frontend, kiểu của nó được khai báo thế nào?
+
+Nguồn: `tsconfig.json` (`strict: true`), `eslint.config.mjs` (`@typescript-eslint/array-type`
+dạng generic), `src/components/**`, `src/hooks/swr/*`, `src/modules/toast/api.ts`,
+`packages/grammar/src/common/conformance.ts`, `core/primitive/Button/index.tsx`.
+
+## FE-TYPING-1 — `type` cho hình dạng, `interface` ở tầng hook
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Props và hình dạng dữ liệu | `export type StarCiAiTurn = { readonly id: string; readonly role: "user" \| "assistant"; … }` (919 `export type X = {` so với 232 `export interface` trong `src/`, 403 so với 6 cho `…Props`) |
+| Case 2 | Tham số hook | `export interface UseQueryCourseSwrParams { displayId?: string }` — phần `interface` tập trung ở `hooks/` và `modules/api`, không ở component |
+| Case 3 | Giao | `export type CourseAdvisorRecommendationCardData = CourseAdvisorRecommendation & { readonly title?: string; … }` |
+| Case 4 | Gói Grammar | `export type ButtonProps = { … }`, `export type GrammarRuleConformance = { … }` — `type` xuyên suốt |
+
+## FE-TYPING-2 — `readonly` trên mọi trường
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Trường props | `readonly measure?: "form" \| "formCompact"` (2336 dòng prop `readonly` so với 69 dòng không) |
+| Case 2 | Object lồng | `readonly action: { readonly href: string; readonly label: string }` |
+| Case 3 | Tập hợp | `readonly turns: ReadonlyArray<StarCiAiTurn>`, `readonly states: Readonly<Record<StarCiAiChatState, string>>` |
+| Case 4 | Khóa dạng tuple | `_key: readonly [string, string]` |
+
+## FE-TYPING-3 — Union literal, không phải boolean, cho trạng thái
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Trạng thái component | `export type StarCiAiChatState = \| "sessionsPending" \| "sessionsFailed" \| "noSession" \| … \| "contextCleared"` (21 thành viên) |
+| Case 2 | Chế độ | `export type StarCiAiMode = "general" \| "history"`; `role: "user" \| "assistant"` |
+| Case 3 | Kho của union | `export const STARCI_AI_CHAT_STATES: ReadonlyArray<StarCiAiChatState> = [ … ]` kề bên kiểu |
+| Case 4 | Cờ thực sự nhị phân | `readonly isLoading?: boolean`, `readonly isPartial?: boolean` — tiền tố `is`/`has` |
+| Case 5 | Từ vựng đóng trong Grammar | `export type ButtonVariant = "primary" \| "secondary" \| "tertiary" \| "outline" \| "ghost"`; `const VARIANTS = { … } as const` |
+
+## FE-TYPING-4 — Mảng
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Mọi kiểu mảng | `ReadonlyArray<string>`, `Array<T>` — không bao giờ `T[]` (lint `@typescript-eslint/array-type: generic`) |
+| Case 2 | Literal đóng băng | `const PENDING_TURN_IDS = ["pending-1", "pending-2"] as const` (252 chỗ `as const` trong `src/`) |
+
+## FE-TYPING-5 — Suy luận và khai báo
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Kiểu trả về của component | suy luận; không có `: JSX.Element` trên bất kỳ component nào trong 441 |
+| Case 2 | Kiểu trả về của helper | khai báo khi là nguyên thủy: `(state: StarCiAiChatState): boolean =>`, `(turn: StarCiAiTurn, partialLabel: string): string =>` |
+| Case 3 | Kiểu trả về của hook | suy luận từ `useSWR<CourseDetail \| null>(…)`; generic gọi tên dữ liệu |
+| Case 4 | Tiện ích async | khai báo: `export const runGraphQLWithToast = async <T>(action: () => Promise<GraphQLResponse<T>>, options: RunGraphQLWithToastOptions = {}): Promise<boolean>` |
+| Case 5 | Literal thu hẹp | `return { mode: "signIn" as const, step: "code" as const, measure: "form" as const }` để một switch trả về union, không phải `string` |
+
+## FE-TYPING-6 — Ép kiểu
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Ép kép | không viết (lint `no-double-cast`) |
+| Case 2 | Ô giả lập trong spec | `data: undefined as unknown` bên trong `vi.hoisted(() => ({ … }))` |
+| Case 3 | Bỏ qua một prop | `void props` thay vì gạch dưới hay ép kiểu |
+
+## FE-TYPING-7 — Enum
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Từ vựng component | không bao giờ là enum; là union chuỗi literal |
+| Case 2 | Tên thao tác GraphQL | `export enum MutationCvBlocks { Create = "create", … }` — 92 enum trong `src/` đều nằm ở `modules/api/graphql` |