@starci/skills 1.1.0

package/knowledge/patterns/fe/comment.md

@@ -0,0 +1,70 @@
+# Comment
+
+This file answers one question: given a frontend declaration or statement, does it carry a
+comment, and what does that comment say?
+
+Sources: `src/components/pages/AuthenticationPage/*`, `blocks/ai/StarCiAiChat/*`,
+`blocks/ai/CourseAdvisorRecommendationCard/*`, `hooks/index.ts`, `hooks/swr/useQueryCourseSwr.ts`,
+`hooks/swr/useMutateAddToCartSwr.ts`, `modules/api/graphql/queries/query-course.ts`,
+`eslint.config.mjs`.
+
+## FE-COMMENT-1 — Every export carries a docblock
+
+415 of 417 non-spec component files contain a `/** */` block; lint `require-export-jsdoc` enforces
+it.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A component | `/** Render the connected cart route. */` · `/** Draw every AI-owner state from resolved fixture data; no transport or translation lives here. */` |
+| Case 2 | A props type | `/** Complete state/data/action contract for the pure advisor surface. */` · `/** Closed leaf props for a button-treatment sample. */` |
+| Case 3 | A class-name export | `/** Messenger-like visual roles owned by the StarCi course-advisor surface. */` · `/** Grammar-owned page frame; this app alias adds no visual override. */` |
+| Case 4 | A constant | `/** Canonical state inventory shared by connected owners and presentation tests. */` · `/** The key prefix, so a caller can revalidate every course read at once. */` |
+| Case 5 | A route | `/** The routed authentication screen. The route mounts one page and makes no drawing decision. */` |
+
+The one-liner states ownership or role ("owned by", "resolved by the connected owner", "no
+transport lives here"), not the name.
+
+## FE-COMMENT-2 — Fields are documented when the name is not enough
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A handler | `/** Called after the panel establishes a session. */ readonly signedIn?: () => void` |
+| Case 2 | A prop whose source matters | `/** URL-owned journey rendered before the browser hydrates stored challenge metadata. */ readonly initialMode?: AuthMode` |
+| Case 3 | A hook param | `/** The short human-facing identifier the route carries - \`fullstack-mastery\`, not a UUID. */ displayId?: string` |
+| Case 4 | A Grammar prop | `/** Pending belongs to the action that started the work and blocks duplicate presses. */ readonly isPending?: boolean` |
+| Case 5 | Self-evident fields | `readonly id: string`, `readonly body: string` carry nothing |
+
+## FE-COMMENT-3 — Decision prose on hooks and documents
+
+Hooks and GraphQL modules carry multi-paragraph docblocks whose paragraphs open with a
+capitalised claim and then give the measured reason.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A key decision | `THE DISPLAY ID IS PART OF THE KEY, which is what makes two course pages in one session safe: …` (`useQueryCourseSwr`) |
+| Case 2 | A rejected alternative | `IT SENDS \`displayId\` AND NEVER \`id\`, and that is a measured decision rather than a preference. … The server answers that with \`success: false, error: COURSE_NOT_FOUND_EXCEPTION\`` |
+| Case 3 | Why the key carries an argument | `THE KEY CARRIES THE COURSE, and it has to. Every hook sharing a key shares its state, so a grid of cards on one key is a grid where pressing ONE card puts every other card's control into the running state` (`useMutateAddToCartSwr`) |
+| Case 4 | Selection rationale | `WHY THE CONTENT FACTS ARE SELECTED AND NOT ASKED FOR. …` (`query-course.ts`) |
+| Case 5 | `@param` | `@param courseId - The course this hook's press is about, or \`undefined\` to stay idle.`; `@param input - {@link AuthenticationPageProps}` appears in one page and is not the norm |
+
+## FE-COMMENT-4 — Line comments are sentences about why
+
+201 `//` lines exist under `src/components` (non-spec). They sit above the statement and explain a
+consequence; none restates the code.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A guard's reason | `// A server-rendered form has no React submit handler yet. Keeping its secret-bearing controls disabled until hydration prevents the browser's native GET fallback from placing an email, password or OTP in the URL when a reader acts before JavaScript attaches.` |
+| Case 2 | Copy decision | `// The transport case deliberately does NOT say the details or the code were wrong, because nobody knows that - the request never got an answer.` |
+| Case 3 | Cache decision | `// The sign-out drops every identity entry, whichever viewer it was cached under, and leaves every other cache namespace - and every non-tuple key - exactly where it was.` |
+| Case 4 | Test stand-in | `// jsdom implements ranges but not their geometry, and the block asks a range where it is so the surface can be placed over it. A fixed rect is the honest stand-in: nothing here has layout.` |
+| Case 5 | Config exception | the block comment above `files: ["src/modules/api/graphql/clients/options.ts"]` in `eslint.config.mjs` states why the exception lives in config and not inline |
+
+## FE-COMMENT-5 — What a comment never contains
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A second language | English only in source (lint `no-second-language-in-source`, `no-second-language-in-path`); user copy lives in `src/messages/{en,vi}.json` |
+| Case 2 | Emoji | none (lint `no-emoji-in-source`) |
+| Case 3 | A lint suppression | `eslint-disable` in 0 files; the config carries the exception with its reason |
+| Case 4 | A restated name | `/** Props for CartPage. */` alone is not observed; the docblock adds what the page owns: `/** The page owns only the route-level composition; CartBlock owns cart state and actions. */` |

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

@@ -0,0 +1,70 @@
+# Chú thích
+
+Tệp này trả lời một câu hỏi: cho một khai báo hay câu lệnh frontend, nó có mang chú thích không,
+và chú thích ấy nói gì?
+
+Nguồn: `src/components/pages/AuthenticationPage/*`, `blocks/ai/StarCiAiChat/*`,
+`blocks/ai/CourseAdvisorRecommendationCard/*`, `hooks/index.ts`, `hooks/swr/useQueryCourseSwr.ts`,
+`hooks/swr/useMutateAddToCartSwr.ts`, `modules/api/graphql/queries/query-course.ts`,
+`eslint.config.mjs`.
+
+## FE-COMMENT-1 — Mọi export đều mang docblock
+
+415 trên 417 tệp component không phải spec chứa một khối `/** */`; lint `require-export-jsdoc`
+ép điều này.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một component | `/** Render the connected cart route. */` · `/** Draw every AI-owner state from resolved fixture data; no transport or translation lives here. */` |
+| Case 2 | Một kiểu props | `/** Complete state/data/action contract for the pure advisor surface. */` · `/** Closed leaf props for a button-treatment sample. */` |
+| Case 3 | Một export class-name | `/** Messenger-like visual roles owned by the StarCi course-advisor surface. */` · `/** Grammar-owned page frame; this app alias adds no visual override. */` |
+| Case 4 | Một hằng | `/** Canonical state inventory shared by connected owners and presentation tests. */` · `/** The key prefix, so a caller can revalidate every course read at once. */` |
+| Case 5 | Một route | `/** The routed authentication screen. The route mounts one page and makes no drawing decision. */` |
+
+Câu một dòng nêu quyền sở hữu hoặc vai trò ("owned by", "resolved by the connected owner", "no
+transport lives here"), không nêu lại tên.
+
+## FE-COMMENT-2 — Trường được chú thích khi tên chưa đủ nói
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một bộ xử lý | `/** Called after the panel establishes a session. */ readonly signedIn?: () => void` |
+| Case 2 | Một prop mà nguồn gốc quan trọng | `/** URL-owned journey rendered before the browser hydrates stored challenge metadata. */ readonly initialMode?: AuthMode` |
+| Case 3 | Một tham số hook | `/** The short human-facing identifier the route carries - \`fullstack-mastery\`, not a UUID. */ displayId?: string` |
+| Case 4 | Một prop Grammar | `/** Pending belongs to the action that started the work and blocks duplicate presses. */ readonly isPending?: boolean` |
+| Case 5 | Trường tự hiển nhiên | `readonly id: string`, `readonly body: string` không mang gì |
+
+## FE-COMMENT-3 — Văn xuôi lý giải quyết định trên hook và tài liệu
+
+Hook và module GraphQL mang docblock nhiều đoạn; mỗi đoạn mở bằng một khẳng định viết hoa rồi đưa
+ra lý do đã đo được.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Quyết định về khóa | `THE DISPLAY ID IS PART OF THE KEY, which is what makes two course pages in one session safe: …` (`useQueryCourseSwr`) |
+| Case 2 | Phương án đã bác | `IT SENDS \`displayId\` AND NEVER \`id\`, and that is a measured decision rather than a preference. … The server answers that with \`success: false, error: COURSE_NOT_FOUND_EXCEPTION\`` |
+| Case 3 | Vì sao khóa mang đối số | `THE KEY CARRIES THE COURSE, and it has to. Every hook sharing a key shares its state, so a grid of cards on one key is a grid where pressing ONE card puts every other card's control into the running state` (`useMutateAddToCartSwr`) |
+| Case 4 | Lý do chọn trường | `WHY THE CONTENT FACTS ARE SELECTED AND NOT ASKED FOR. …` (`query-course.ts`) |
+| Case 5 | `@param` | `@param courseId - The course this hook's press is about, or \`undefined\` to stay idle.`; `@param input - {@link AuthenticationPageProps}` xuất hiện ở một page và không phải chuẩn chung |
+
+## FE-COMMENT-4 — Chú thích dòng là câu văn về lý do
+
+201 dòng `//` tồn tại dưới `src/components` (không kể spec). Chúng đứng trên câu lệnh và giải
+thích hệ quả; không dòng nào nhắc lại mã.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Lý do của một chốt chặn | `// A server-rendered form has no React submit handler yet. Keeping its secret-bearing controls disabled until hydration prevents the browser's native GET fallback from placing an email, password or OTP in the URL when a reader acts before JavaScript attaches.` |
+| Case 2 | Quyết định câu chữ | `// The transport case deliberately does NOT say the details or the code were wrong, because nobody knows that - the request never got an answer.` |
+| Case 3 | Quyết định cache | `// The sign-out drops every identity entry, whichever viewer it was cached under, and leaves every other cache namespace - and every non-tuple key - exactly where it was.` |
+| Case 4 | Vật thế trong kiểm thử | `// jsdom implements ranges but not their geometry, and the block asks a range where it is so the surface can be placed over it. A fixed rect is the honest stand-in: nothing here has layout.` |
+| Case 5 | Ngoại lệ cấu hình | khối chú thích trên `files: ["src/modules/api/graphql/clients/options.ts"]` trong `eslint.config.mjs` nêu vì sao ngoại lệ sống trong cấu hình chứ không nội tuyến |
+
+## FE-COMMENT-5 — Thứ một chú thích không bao giờ chứa
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Ngôn ngữ thứ hai | chỉ tiếng Anh trong mã nguồn (lint `no-second-language-in-source`, `no-second-language-in-path`); câu chữ cho người dùng nằm trong `src/messages/{en,vi}.json` |
+| Case 2 | Emoji | không có (lint `no-emoji-in-source`) |
+| Case 3 | Tắt lint | `eslint-disable` trong 0 tệp; cấu hình mang ngoại lệ kèm lý do |
+| Case 4 | Nhắc lại tên | không thấy `/** Props for CartPage. */` đứng một mình; docblock bổ sung page sở hữu gì: `/** The page owns only the route-level composition; CartBlock owns cart state and actions. */` |

package/knowledge/patterns/fe/error.md

@@ -0,0 +1,61 @@
+# Error
+
+This file answers one question: given a failure in the frontend, how is it represented and where
+does it go?
+
+Sources: `src/components/blocks/**/component.tsx`, `blocks/commerce/CartBlock/index.spec.tsx`,
+`src/modules/toast/api.ts`, `src/modules/api/graphql/types.ts`, `src/hooks/swr/*`,
+`packages/grammar/src/common/conformance.ts`.
+
+## FE-ERROR-1 — Failure is a state of the pure half
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | The generic case | `"failed"` is a member of the block state union in 219 `component.tsx` files; the connected half maps SWR `error` to it and the pure half draws it |
+| Case 2 | Several failure origins | `"sessionsFailed" \| "historyFailed" \| "streamFailed" \| "quotaRejected"` in `StarCiAiChatState`; `const stateNeedsRetry = (state) => state === "sessionsFailed" \|\| state === "historyFailed" \|\| state === "streamFailed" \|\| state === "quotaRejected"` |
+| Case 3 | Failure copy | resolved by the connected half into `labels.states[props.state]` and drawn as an assistant turn: `{ id: \`state-${props.state}\`, role: "assistant", body: labels.states[props.state] }` |
+| Case 4 | Retry | an action on `on`: `<Button variant="primary" size="sm" onPress={props.on?.retry}>{labels.retry}</Button>` |
+| Case 5 | Connected spec | asserts the mapping: `mocks.cart.isLoading = true … expect(mocks.input?.blockState).toBe("pending")` |
+
+## FE-ERROR-2 — The GraphQL envelope
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Every response | `{ success, message, error, data }` selected in each document (`query Course … { success message error data { … } }`) and typed `GraphQLResponse<T>` in `modules/api/graphql/types.ts` |
+| Case 2 | A read hook unwraps | `return result.data?.course?.data ?? null` — a missing payload becomes `null` data, not a throw |
+| Case 3 | A write with feedback | `runGraphQLWithToast(action, options): Promise<boolean>` — "Execute one GraphQL write and surface both transport and typed-envelope failures" |
+| Case 4 | Localised default copy | `const DEFAULT_MESSAGES: ToastMessages = { successTitle: "Success", errorTitle: "Error", unauthorizedTitle: "Unauthorized", … }` overridable per call through `messages` |
+
+## FE-ERROR-3 — `throw new Error` where silence would be wrong
+
+52 `throw new Error(…)` sites exist in `src/` (non-spec). They mark a result that the code cannot
+continue without.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Empty payload on a required read | `if (value === undefined) throw new Error("Course Community returned no data")` |
+| Case 2 | Mutation returned nothing | `if (result === null) throw new Error("Flashcard review completion returned no result")` |
+| Case 3 | Slot used outside its owner | `if (value === undefined) throw new Error("CourseFoundationCategoryBlock slots must be rendered inside CourseFoundationCategoryBlockBase")` |
+| Case 4 | Offline | `throw new Error("offline")` inside a fetcher so SWR records `error` |
+| Case 5 | Custom class | one exists: `class PersonalProjectEnrollmentDeniedError extends Error` in `useQueryPersonalProjectTaskWorkspaceSwr.ts`; not a pattern |
+
+## FE-ERROR-4 — Propagation
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Inside a hook | not caught; SWR stores it and the connected half reads `query.error` (`catch (` appears in 3 files across `src/`) |
+| Case 2 | Inside a write action | `runGraphQLWithToast` returns `false` and toasts; the caller flips a local state (`payment.hasFailed`) |
+| Case 3 | Render crash | `src/app/global-error.tsx` |
+| Case 4 | Telemetry | `src/config/sentry.ts`, `src/instrumentation.ts`, `instrumentation-client.ts` |
+
+## FE-ERROR-5 — Grammar package
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Invalid definition at module init | `throw new TypeError(\`Invalid ${definition.familyId} Grammar conformance: missing=[…], unknown=[…]\`)` in `defineGrammarRuleConformance` |
+| Case 2 | Invalid vocabulary value | `assertPresentationState("unknown")` throws `TypeError` (`common/index.test.mjs`) |
+
+## Open question
+
+Whether a typed error class should replace `throw new Error("…")` for the "no data" cases: one
+custom class against 52 plain throws, so the plain form is what the code does today.

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

@@ -0,0 +1,61 @@
+# Lỗi
+
+Tệp này trả lời một câu hỏi: cho một thất bại trong frontend, nó được biểu diễn ra sao và đi về
+đâu?
+
+Nguồn: `src/components/blocks/**/component.tsx`, `blocks/commerce/CartBlock/index.spec.tsx`,
+`src/modules/toast/api.ts`, `src/modules/api/graphql/types.ts`, `src/hooks/swr/*`,
+`packages/grammar/src/common/conformance.ts`.
+
+## FE-ERROR-1 — Thất bại là một trạng thái của nửa thuần
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Trường hợp chung | `"failed"` là một thành viên của union trạng thái block trong 219 tệp `component.tsx`; nửa nối ánh xạ `error` của SWR sang nó và nửa thuần vẽ nó |
+| Case 2 | Nhiều nguồn thất bại | `"sessionsFailed" \| "historyFailed" \| "streamFailed" \| "quotaRejected"` trong `StarCiAiChatState`; `const stateNeedsRetry = (state) => state === "sessionsFailed" \|\| state === "historyFailed" \|\| state === "streamFailed" \|\| state === "quotaRejected"` |
+| Case 3 | Câu chữ thất bại | được nửa nối giải vào `labels.states[props.state]` và vẽ như một lượt trợ lý: `{ id: \`state-${props.state}\`, role: "assistant", body: labels.states[props.state] }` |
+| Case 4 | Thử lại | một hành động trên `on`: `<Button variant="primary" size="sm" onPress={props.on?.retry}>{labels.retry}</Button>` |
+| Case 5 | Spec nửa nối | khẳng định phép ánh xạ: `mocks.cart.isLoading = true … expect(mocks.input?.blockState).toBe("pending")` |
+
+## FE-ERROR-2 — Phong bì GraphQL
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Mọi phản hồi | `{ success, message, error, data }` được chọn trong từng tài liệu (`query Course … { success message error data { … } }`) và định kiểu `GraphQLResponse<T>` trong `modules/api/graphql/types.ts` |
+| Case 2 | Hook đọc bóc phong bì | `return result.data?.course?.data ?? null` — thiếu payload thành dữ liệu `null`, không ném |
+| Case 3 | Ghi có phản hồi | `runGraphQLWithToast(action, options): Promise<boolean>` — thực thi một lệnh ghi GraphQL và làm nổi cả thất bại vận chuyển lẫn thất bại trong phong bì có kiểu |
+| Case 4 | Câu chữ mặc định có bản địa hóa | `const DEFAULT_MESSAGES: ToastMessages = { successTitle: "Success", errorTitle: "Error", unauthorizedTitle: "Unauthorized", … }` ghi đè theo từng lần gọi qua `messages` |
+
+## FE-ERROR-3 — `throw new Error` nơi im lặng sẽ là sai
+
+52 chỗ `throw new Error(…)` tồn tại trong `src/` (không kể spec). Chúng đánh dấu một kết quả mà mã
+không thể tiếp tục nếu thiếu.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Payload rỗng ở lượt đọc bắt buộc | `if (value === undefined) throw new Error("Course Community returned no data")` |
+| Case 2 | Mutation không trả gì | `if (result === null) throw new Error("Flashcard review completion returned no result")` |
+| Case 3 | Khe dùng ngoài chủ sở hữu | `if (value === undefined) throw new Error("CourseFoundationCategoryBlock slots must be rendered inside CourseFoundationCategoryBlockBase")` |
+| Case 4 | Ngoại tuyến | `throw new Error("offline")` bên trong một fetcher để SWR ghi nhận `error` |
+| Case 5 | Lớp tùy chỉnh | có đúng một: `class PersonalProjectEnrollmentDeniedError extends Error` trong `useQueryPersonalProjectTaskWorkspaceSwr.ts`; không phải mẫu |
+
+## FE-ERROR-4 — Lan truyền
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Bên trong hook | không bắt; SWR lưu nó và nửa nối đọc `query.error` (`catch (` xuất hiện trong 3 tệp toàn `src/`) |
+| Case 2 | Bên trong hành động ghi | `runGraphQLWithToast` trả `false` và hiện toast; bên gọi lật một state cục bộ (`payment.hasFailed`) |
+| Case 3 | Sập khi vẽ | `src/app/global-error.tsx` |
+| Case 4 | Đo xa | `src/config/sentry.ts`, `src/instrumentation.ts`, `instrumentation-client.ts` |
+
+## FE-ERROR-5 — Gói Grammar
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Định nghĩa không hợp lệ lúc khởi tạo module | `throw new TypeError(\`Invalid ${definition.familyId} Grammar conformance: missing=[…], unknown=[…]\`)` trong `defineGrammarRuleConformance` |
+| Case 2 | Giá trị từ vựng không hợp lệ | `assertPresentationState("unknown")` ném `TypeError` (`common/index.test.mjs`) |
+
+## Câu hỏi để ngỏ
+
+Có nên thay `throw new Error("…")` bằng một lớp lỗi có kiểu cho các trường hợp "không có dữ liệu"
+hay không: một lớp tùy chỉnh so với 52 lần ném trần, nên dạng trần là điều mã đang làm hôm nay.

package/knowledge/patterns/fe/folder.md

@@ -0,0 +1,98 @@
+# Folder
+
+This file answers one question: given a piece of frontend code, which directory and which file
+name does it get?
+
+Sources: `starci-academy-fe/src/components/**`, `src/hooks/**`, `src/modules/api/**`, `src/app/**`,
+`packages/grammar/src/**`. Counts are file counts at the time of reading.
+
+## FE-FOLDER-1 — Tier directories
+
+`src/components/` holds eight tier folders. Blocks are grouped by product domain; pages and leaves
+are flat.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A reusable fixed visual unit | `src/components/leaves/<Name>/` (40 units, flat) |
+| Case 2 | A feature unit with a connected half | `src/components/blocks/<domain>/<Name>/` (109 units under 11 domains: `ai auth coding commerce community courses dashboard learn locale profile search`) |
+| Case 3 | A routed screen | `src/components/pages/<Name>Page/` (50 units, flat) |
+| Case 4 | Other tiers present | `branches/`, `composites/`, `layouts/`, `overlays/`, `product-shells/` |
+
+## FE-FOLDER-2 — The file set of one unit
+
+One unit is one PascalCase folder. Its files carry fixed names; the unit name is the folder, never
+the file.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Page unit (`pages/AuthenticationPage/`) | `classNames.ts` · `component.tsx` · `index.tsx` |
+| Case 2 | Page unit with specs (`pages/CartPage/`) | `component.tsx` · `index.spec.tsx` · `index.tsx` |
+| Case 3 | Block unit (`blocks/ai/StarCiAiChat/`) | `classNames.ts` · `component.spec.tsx` · `component.tsx` · `index.spec.tsx` · `index.tsx` |
+| Case 4 | Leaf unit (`leaves/ButtonStateSample/`) | `classNames.ts` · `index.tsx` — a leaf has no `component.tsx`, because it has no connected half |
+
+Counts across pages (50): `index.tsx` 49, `component.tsx` 49, `component.spec.tsx` 42,
+`index.spec.tsx` 24, `audit.md` 22, `classNames.ts` 9. Across blocks (109): `component.tsx` 101,
+`index.tsx` 95, `classNames.ts` 76, `index.spec.tsx` 61, `component.spec.tsx` 55. Across leaves
+(40): `index.tsx` 40, `classNames.ts` 33, `index.spec.tsx` 19.
+
+`classNames.ts` is present only when the unit owns class strings. A page that composes a block
+into a Grammar frame usually has none; the 9 pages that have one alias a Grammar page frame:
+
+```ts
+// pages/AuthenticationPage/classNames.ts
+import { cn } from "@heroui/react"
+import { formPageClassName } from "@starci/grammar/common"
+
+/** Grammar-owned page frame; this app alias adds no visual override. */
+export const authenticationPageClassName = cn(formPageClassName)
+```
+
+## FE-FOLDER-3 — Route files mount one page
+
+`src/app/[lang]/**/page.tsx` is the only place a default export exists (67 in `src/app`, 0 in
+`src/components`).
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A route | `app/[lang]/authentication/page.tsx`: `import { AuthenticationPage } from "@/components/pages/AuthenticationPage"` … `const AuthenticationRoute = () => <AuthenticationPage {...{}} />` … `export default AuthenticationRoute` |
+| Case 2 | Global app files | `app/globals.css`, `app/providers.tsx`, `app/global-error.tsx`, `app/sitemap.ts`, `app/robots.ts`, each with a sibling `.spec` |
+
+## FE-FOLDER-4 — Data layer placement
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A read hook | `src/hooks/swr/useQuery<Thing>Swr.ts` (80) with sibling `.spec.ts` |
+| Case 2 | A write hook | `src/hooks/swr/useMutate<Thing>Swr.ts` (32) with sibling `.spec.ts` |
+| Case 3 | Auth / socket hooks | `src/hooks/auth/useSessionToken.ts`, `src/hooks/socketio/**` |
+| Case 4 | The one door for components | `src/hooks/index.ts` re-exports hooks only ("Hooks ONLY. Types, cache keys and query modules stay behind their own paths") |
+| Case 5 | A GraphQL document | `src/modules/api/graphql/queries/query-<thing>.ts`, `src/modules/api/graphql/mutations/mutation-<thing>.ts` |
+| Case 6 | Response/request types | `src/modules/api/graphql/queries/types/<thing>.ts` |
+| Case 7 | Non-API modules | `src/modules/{ai,code,learn,routing,search,theme,toast,types,utils}/` |
+
+## FE-FOLDER-5 — Grammar package unit
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A Grammar component | `packages/grammar/src/core/<primitive|composite|branch|composition>/<Name>/index.tsx` (39 `index.tsx`) |
+| Case 2 | Its class strings | sibling `classNames.ts` (13), e.g. `core/branch/Rail/classNames.ts` |
+| Case 3 | Its spec | sibling `index.spec.tsx` (24); CSS proof in `styles.spec.ts` (6) |
+| Case 4 | Family entry | `core/index.ts`, `core/styles.css`, `core/dna.ts`; `common/index.ts` re-exports `state.js`, `spacing.js`, `conformance.js`, `renderers.js`, `registry.js` |
+| Case 5 | Built-output proof | `common/index.test.mjs`, `core/index.test.mjs`, `package-boundary.test.mjs` (node:test against `dist/`) |
+
+## FE-FOLDER-6 — What a unit folder does not hold
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A second component in the same folder | Not observed in 87 of 109 block folders; the unit is one export per `index.tsx`/`component.tsx` |
+| Case 2 | Class strings in `component.tsx` | Never; they go to `classNames.ts` (lint `class-names-in-colocated-file`, `no-inline-class-name`) |
+| Case 3 | A `__tests__/` folder | 0 across `src/`; specs sit beside their file |
+| Case 4 | A `helpers/` or `utils/` folder | 0 under `src/components` (lint `no-helper-folder-in-components`) |
+
+## Open question — extra files inside block folders
+
+22 files under `src/components/blocks` fall outside the five canonical names: the
+`blocks/profile/overview/` sub-tree (`OverviewCourses.tsx`, `SkillSnapshot.tsx`, `shared.ts`,
+`useOverviewEvidence.ts`, …), `learn/CourseMockInterviewResultBlock/verdict.ts`,
+`profile/ProfileCvBuilder/buildCvTexSource.ts`, and three `classNames.spec.ts`/`styles.spec.ts`.
+No dominant convention exists for where a block-private helper module goes, so this file does not
+legislate one.

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

@@ -0,0 +1,95 @@
+# Thư mục
+
+Tệp này trả lời một câu hỏi: cho một mẩu mã frontend, nó nằm ở thư mục nào và mang tên tệp gì?
+
+Nguồn: `starci-academy-fe/src/components/**`, `src/hooks/**`, `src/modules/api/**`, `src/app/**`,
+`packages/grammar/src/**`. Các con số là số tệp tại thời điểm đọc.
+
+## FE-FOLDER-1 — Thư mục theo tầng
+
+`src/components/` chứa tám thư mục tầng. Block được gom theo miền sản phẩm; page và leaf nằm phẳng.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một đơn vị hình ảnh cố định, tái dùng | `src/components/leaves/<Name>/` (40 đơn vị, phẳng) |
+| Case 2 | Một đơn vị tính năng có nửa nối dữ liệu | `src/components/blocks/<domain>/<Name>/` (109 đơn vị trong 11 miền: `ai auth coding commerce community courses dashboard learn locale profile search`) |
+| Case 3 | Một màn hình có route | `src/components/pages/<Name>Page/` (50 đơn vị, phẳng) |
+| Case 4 | Các tầng khác đang có | `branches/`, `composites/`, `layouts/`, `overlays/`, `product-shells/` |
+
+## FE-FOLDER-2 — Bộ tệp của một đơn vị
+
+Một đơn vị là một thư mục PascalCase. Các tệp bên trong mang tên cố định; tên đơn vị là tên thư
+mục, không bao giờ là tên tệp.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Đơn vị page (`pages/AuthenticationPage/`) | `classNames.ts` · `component.tsx` · `index.tsx` |
+| Case 2 | Đơn vị page có spec (`pages/CartPage/`) | `component.tsx` · `index.spec.tsx` · `index.tsx` |
+| Case 3 | Đơn vị block (`blocks/ai/StarCiAiChat/`) | `classNames.ts` · `component.spec.tsx` · `component.tsx` · `index.spec.tsx` · `index.tsx` |
+| Case 4 | Đơn vị leaf (`leaves/ButtonStateSample/`) | `classNames.ts` · `index.tsx` — leaf không có `component.tsx`, vì nó không có nửa nối dữ liệu |
+
+Số đếm trong pages (50): `index.tsx` 49, `component.tsx` 49, `component.spec.tsx` 42,
+`index.spec.tsx` 24, `audit.md` 22, `classNames.ts` 9. Trong blocks (109): `component.tsx` 101,
+`index.tsx` 95, `classNames.ts` 76, `index.spec.tsx` 61, `component.spec.tsx` 55. Trong leaves
+(40): `index.tsx` 40, `classNames.ts` 33, `index.spec.tsx` 19.
+
+`classNames.ts` chỉ có mặt khi đơn vị sở hữu chuỗi class. Một page chỉ ghép block vào khung
+Grammar thường không có tệp này; 9 page có tệp này đều chỉ đặt bí danh cho khung trang của Grammar:
+
+```ts
+// pages/AuthenticationPage/classNames.ts
+import { cn } from "@heroui/react"
+import { formPageClassName } from "@starci/grammar/common"
+
+/** Grammar-owned page frame; this app alias adds no visual override. */
+export const authenticationPageClassName = cn(formPageClassName)
+```
+
+## FE-FOLDER-3 — Tệp route gắn đúng một page
+
+`src/app/[lang]/**/page.tsx` là nơi duy nhất có default export (67 trong `src/app`, 0 trong
+`src/components`).
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một route | `app/[lang]/authentication/page.tsx`: `import { AuthenticationPage } from "@/components/pages/AuthenticationPage"` … `const AuthenticationRoute = () => <AuthenticationPage {...{}} />` … `export default AuthenticationRoute` |
+| Case 2 | Các tệp toàn cục của app | `app/globals.css`, `app/providers.tsx`, `app/global-error.tsx`, `app/sitemap.ts`, `app/robots.ts`, mỗi tệp có `.spec` kề bên |
+
+## FE-FOLDER-4 — Vị trí tầng dữ liệu
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Hook đọc | `src/hooks/swr/useQuery<Thing>Swr.ts` (80) kèm `.spec.ts` kề bên |
+| Case 2 | Hook ghi | `src/hooks/swr/useMutate<Thing>Swr.ts` (32) kèm `.spec.ts` kề bên |
+| Case 3 | Hook xác thực / socket | `src/hooks/auth/useSessionToken.ts`, `src/hooks/socketio/**` |
+| Case 4 | Cánh cửa duy nhất cho component | `src/hooks/index.ts` chỉ re-export hook (docblock ghi rõ chỉ hook; kiểu, khóa cache và module truy vấn nằm sau đường dẫn riêng của chúng) |
+| Case 5 | Một tài liệu GraphQL | `src/modules/api/graphql/queries/query-<thing>.ts`, `src/modules/api/graphql/mutations/mutation-<thing>.ts` |
+| Case 6 | Kiểu request/response | `src/modules/api/graphql/queries/types/<thing>.ts` |
+| Case 7 | Module ngoài API | `src/modules/{ai,code,learn,routing,search,theme,toast,types,utils}/` |
+
+## FE-FOLDER-5 — Đơn vị trong gói Grammar
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một component Grammar | `packages/grammar/src/core/<primitive|composite|branch|composition>/<Name>/index.tsx` (39 `index.tsx`) |
+| Case 2 | Chuỗi class của nó | `classNames.ts` kề bên (13), ví dụ `core/branch/Rail/classNames.ts` |
+| Case 3 | Spec của nó | `index.spec.tsx` kề bên (24); chứng minh CSS trong `styles.spec.ts` (6) |
+| Case 4 | Cửa vào của họ | `core/index.ts`, `core/styles.css`, `core/dna.ts`; `common/index.ts` re-export `state.js`, `spacing.js`, `conformance.js`, `renderers.js`, `registry.js` |
+| Case 5 | Chứng minh bản build | `common/index.test.mjs`, `core/index.test.mjs`, `package-boundary.test.mjs` (node:test chạy trên `dist/`) |
+
+## FE-FOLDER-6 — Thứ một thư mục đơn vị không chứa
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một component thứ hai trong cùng thư mục | Không thấy ở 87 trên 109 thư mục block; đơn vị là một export cho mỗi `index.tsx`/`component.tsx` |
+| Case 2 | Chuỗi class trong `component.tsx` | Không bao giờ; chúng đi vào `classNames.ts` (lint `class-names-in-colocated-file`, `no-inline-class-name`) |
+| Case 3 | Thư mục `__tests__/` | 0 trong toàn bộ `src/`; spec nằm cạnh tệp của nó |
+| Case 4 | Thư mục `helpers/` hay `utils/` | 0 dưới `src/components` (lint `no-helper-folder-in-components`) |
+
+## Câu hỏi để ngỏ — tệp phụ trong thư mục block
+
+22 tệp dưới `src/components/blocks` nằm ngoài năm tên chuẩn: cây con `blocks/profile/overview/`
+(`OverviewCourses.tsx`, `SkillSnapshot.tsx`, `shared.ts`, `useOverviewEvidence.ts`, …),
+`learn/CourseMockInterviewResultBlock/verdict.ts`, `profile/ProfileCvBuilder/buildCvTexSource.ts`,
+và ba `classNames.spec.ts`/`styles.spec.ts`. Chưa có quy ước chiếm ưu thế cho chỗ đặt một module
+helper riêng của block, nên tệp này không áp đặt.

package/knowledge/patterns/fe/function.md

@@ -0,0 +1,70 @@
+# Function
+
+This file answers one question: given a frontend component, hook or helper, what shape does the
+function take, what does it receive, and what does it return?
+
+Sources: `src/components/pages/AuthenticationPage/*`, `pages/CartPage/index.tsx`,
+`blocks/ai/StarCiAiChat/*`, `blocks/ai/CourseAdvisorRecommendationCard/*`,
+`leaves/ButtonStateSample/index.tsx`, `hooks/swr/useQueryCourseSwr.ts`,
+`hooks/swr/useMutateAddToCartSwr.ts`, `packages/grammar/src/core/primitive/Button/index.tsx`.
+
+## FE-FUNCTION-1 — A component is an arrow const with one `props` parameter
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Any app component | `export const AuthenticationPageBase = (props: AuthenticationPageProps) => { … }` (441 `export const X = (` against 0 `export function` under `src/components`; 428 take `(props: XProps)`, 0 destructure at the signature) |
+| Case 2 | Reading fields | `const { on } = props` at the top, or `props.props.labels`, `props.state` inline |
+| Case 3 | Expression body when there is no local state | `export const ButtonStateSample = (props: ButtonStateSampleProps) => ( <span …>{props.props.label}</span> )` |
+| Case 4 | Grammar package component | destructures with defaults at the signature: `export const Button = ({ children, variant = "secondary", size = "md", type = "button", …, onPress }: ButtonProps) => …` — the package convention differs from the app convention; each side is internally consistent |
+
+## FE-FUNCTION-2 — The three-part contract of a pure half
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Full block contract | `export type StarCiAiChatProps = { readonly state: StarCiAiChatState; readonly props: StarCiAiChatData; readonly on?: StarCiAiChatActions }` (`state`/`blockState` in 85, `props:` in 78, `on?:` in 69 of 101 block `component.tsx`) |
+| Case 2 | Leaf contract | `export type ButtonStateSampleProps = { readonly props: ButtonStateSampleData; readonly isLoading?: boolean }` |
+| Case 3 | Card with an action slot | `{ readonly props: CourseAdvisorRecommendationCardData; readonly isLoading?: boolean; readonly action: { readonly href: string; readonly label: string } }` |
+| Case 4 | Page with only actions | `{ readonly measure?: "form" \| "formCompact"; readonly initialMode?: AuthMode; readonly initialStep?: "details" \| "code"; readonly on?: AuthenticationPageActions }` |
+
+## FE-FUNCTION-3 — Where the props type goes
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Pure half | Declared in `component.tsx` directly above the component, together with its `Data`, `Labels`, `Actions`, `State` parts |
+| Case 2 | Connected half that takes input | Declared in `index.tsx`: `export type CourseAdvisorRecommendationCardProps = { readonly recommendation: CourseAdvisorRecommendation }` |
+| Case 3 | Connected half that takes nothing | `export type CartPageProps = Record<never, never>` and the body starts with `void props` (59 index files; 34 use `Record<never, never>`) |
+| Case 4 | Local sub-render | `type TurnProps = { readonly turn: StarCiAiTurn; … }` unexported, above `const Turn` |
+
+## FE-FUNCTION-4 — What each half does
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Connected half | `"use client"`; calls `useTranslations`, `useLocale`, `useRouter`, `useQuery…Swr`; resolves every label and fact; returns `<XBase state=… props={{ … }} on={{ … }} />` (49/49 page `index.tsx` and 89/109 block `index.tsx` carry `"use client"`) |
+| Case 2 | Pure half | No `"use client"` (0/49 pages, 3/109 blocks); no runtime import from `@/hooks` or `@/modules/api` (0 of 150 `component.tsx`; 18 import a type only) |
+| Case 3 | Route-derived input | `const routeState = (value: string \| null) => { switch (value) { case "sign-up": return { mode: "signUp" as const, step: "details" as const, measure: "form" as const } … } }` in `index.tsx`, then `const initial = routeState(authState)` |
+| Case 4 | Navigation as an action | `on={{ signedIn: () => router.replace("/dashboard") }}` |
+
+## FE-FUNCTION-5 — When a helper is extracted
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A boolean over the state union | `const stateNeedsRetry = (state: StarCiAiChatState): boolean => state === "sessionsFailed" \|\| …` above the component (11 of 101 block `component.tsx` hold such consts) |
+| Case 2 | A string builder | `const turnMarkdown = (turn: StarCiAiTurn, partialLabel: string): string => { … }` |
+| Case 3 | A repeated JSX fragment | `const Turn = (props: TurnProps) => { … }` in the same file, not a new folder |
+| Case 4 | A branch inside the render | an IIFE: `const transcript = (() => { if (…) return …; if (…) return …; return … })()` |
+| Case 5 | A class variant | goes to `classNames.ts` as `getAiChatBubbleClassName(role)` |
+
+## FE-FUNCTION-6 — Hook shape
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Read | `export const useQueryCourseSwr = ({ displayId }: UseQueryCourseSwrParams = {}) => { const viewer = useViewerKey(); return useSWR<CourseDetail \| null>(displayId === undefined ? null : [QUERY_COURSE_SWR_KEY, displayId, viewer ?? "guest"], async () => { const result = await queryCourse({ request: { displayId } }); return result.data?.course?.data ?? null }) }` |
+| Case 2 | Write | `export const useMutateAddToCartSwr = (courseId?: string) => useSWRMutation(courseId === undefined ? null : [MUTATE_ADD_TO_CART_SWR_KEY, courseId], async (_key: readonly [string, string], { arg }: AddToCartTrigger) => mutationAddToCart({ courseId: arg.courseId }))` |
+| Case 3 | Return | the SWR result is returned as-is; the component reads `query.data`, `query.isLoading`, `checkout.trigger`, `checkout.isMutating` |
+| Case 4 | Key | `null` when the input is missing; the viewer identity is part of a read key |
+
+## FE-FUNCTION-7 — Route file
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Every `page.tsx` | `const AuthenticationRoute = () => <AuthenticationPage {...{}} />` then `export default AuthenticationRoute` — the route makes no drawing decision |

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

@@ -0,0 +1,70 @@
+# Hàm
+
+Tệp này trả lời một câu hỏi: cho một component, hook hay helper frontend, hàm có hình dạng gì,
+nhận gì, và trả về gì?
+
+Nguồn: `src/components/pages/AuthenticationPage/*`, `pages/CartPage/index.tsx`,
+`blocks/ai/StarCiAiChat/*`, `blocks/ai/CourseAdvisorRecommendationCard/*`,
+`leaves/ButtonStateSample/index.tsx`, `hooks/swr/useQueryCourseSwr.ts`,
+`hooks/swr/useMutateAddToCartSwr.ts`, `packages/grammar/src/core/primitive/Button/index.tsx`.
+
+## FE-FUNCTION-1 — Component là một arrow const với một tham số `props`
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Mọi component trong app | `export const AuthenticationPageBase = (props: AuthenticationPageProps) => { … }` (441 `export const X = (` so với 0 `export function` dưới `src/components`; 428 nhận `(props: XProps)`, 0 phá cấu trúc ngay tại chữ ký) |
+| Case 2 | Đọc trường | `const { on } = props` ở đầu thân, hoặc `props.props.labels`, `props.state` ngay tại chỗ |
+| Case 3 | Thân biểu thức khi không có state cục bộ | `export const ButtonStateSample = (props: ButtonStateSampleProps) => ( <span …>{props.props.label}</span> )` |
+| Case 4 | Component trong gói Grammar | phá cấu trúc kèm mặc định tại chữ ký: `export const Button = ({ children, variant = "secondary", size = "md", type = "button", …, onPress }: ButtonProps) => …` — quy ước của gói khác quy ước của app; mỗi bên nhất quán nội bộ |
+
+## FE-FUNCTION-2 — Hợp đồng ba phần của nửa thuần
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Hợp đồng block đầy đủ | `export type StarCiAiChatProps = { readonly state: StarCiAiChatState; readonly props: StarCiAiChatData; readonly on?: StarCiAiChatActions }` (`state`/`blockState` ở 85, `props:` ở 78, `on?:` ở 69 trên 101 `component.tsx` của block) |
+| Case 2 | Hợp đồng leaf | `export type ButtonStateSampleProps = { readonly props: ButtonStateSampleData; readonly isLoading?: boolean }` |
+| Case 3 | Thẻ có khe hành động | `{ readonly props: CourseAdvisorRecommendationCardData; readonly isLoading?: boolean; readonly action: { readonly href: string; readonly label: string } }` |
+| Case 4 | Page chỉ có hành động | `{ readonly measure?: "form" \| "formCompact"; readonly initialMode?: AuthMode; readonly initialStep?: "details" \| "code"; readonly on?: AuthenticationPageActions }` |
+
+## FE-FUNCTION-3 — Kiểu props đặt ở đâu
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Nửa thuần | Khai báo trong `component.tsx` ngay trên component, cùng các phần `Data`, `Labels`, `Actions`, `State` |
+| Case 2 | Nửa nối có đầu vào | Khai báo trong `index.tsx`: `export type CourseAdvisorRecommendationCardProps = { readonly recommendation: CourseAdvisorRecommendation }` |
+| Case 3 | Nửa nối không nhận gì | `export type CartPageProps = Record<never, never>` và thân bắt đầu bằng `void props` (59 tệp index; 34 dùng `Record<never, never>`) |
+| Case 4 | Bộ vẽ con cục bộ | `type TurnProps = { readonly turn: StarCiAiTurn; … }` không export, đặt trên `const Turn` |
+
+## FE-FUNCTION-4 — Mỗi nửa làm gì
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Nửa nối | `"use client"`; gọi `useTranslations`, `useLocale`, `useRouter`, `useQuery…Swr`; giải mọi nhãn và dữ kiện; trả về `<XBase state=… props={{ … }} on={{ … }} />` (49/49 `index.tsx` của page và 89/109 `index.tsx` của block mang `"use client"`) |
+| Case 2 | Nửa thuần | Không `"use client"` (0/49 page, 3/109 block); không import lúc chạy từ `@/hooks` hay `@/modules/api` (0 trên 150 `component.tsx`; 18 tệp chỉ import kiểu) |
+| Case 3 | Đầu vào suy từ route | `const routeState = (value: string \| null) => { switch (value) { case "sign-up": return { mode: "signUp" as const, step: "details" as const, measure: "form" as const } … } }` trong `index.tsx`, rồi `const initial = routeState(authState)` |
+| Case 4 | Điều hướng là một hành động | `on={{ signedIn: () => router.replace("/dashboard") }}` |
+
+## FE-FUNCTION-5 — Khi nào tách helper
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một boolean trên union trạng thái | `const stateNeedsRetry = (state: StarCiAiChatState): boolean => state === "sessionsFailed" \|\| …` đặt trên component (11 trên 101 `component.tsx` của block có const như vậy) |
+| Case 2 | Một bộ dựng chuỗi | `const turnMarkdown = (turn: StarCiAiTurn, partialLabel: string): string => { … }` |
+| Case 3 | Một mảnh JSX lặp lại | `const Turn = (props: TurnProps) => { … }` trong cùng tệp, không mở thư mục mới |
+| Case 4 | Một nhánh bên trong phần vẽ | một IIFE: `const transcript = (() => { if (…) return …; if (…) return …; return … })()` |
+| Case 5 | Một biến thể class | đi vào `classNames.ts` dưới dạng `getAiChatBubbleClassName(role)` |
+
+## FE-FUNCTION-6 — Hình dạng hook
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Đọc | `export const useQueryCourseSwr = ({ displayId }: UseQueryCourseSwrParams = {}) => { const viewer = useViewerKey(); return useSWR<CourseDetail \| null>(displayId === undefined ? null : [QUERY_COURSE_SWR_KEY, displayId, viewer ?? "guest"], async () => { const result = await queryCourse({ request: { displayId } }); return result.data?.course?.data ?? null }) }` |
+| Case 2 | Ghi | `export const useMutateAddToCartSwr = (courseId?: string) => useSWRMutation(courseId === undefined ? null : [MUTATE_ADD_TO_CART_SWR_KEY, courseId], async (_key: readonly [string, string], { arg }: AddToCartTrigger) => mutationAddToCart({ courseId: arg.courseId }))` |
+| Case 3 | Trả về | kết quả SWR được trả nguyên; component đọc `query.data`, `query.isLoading`, `checkout.trigger`, `checkout.isMutating` |
+| Case 4 | Khóa | `null` khi thiếu đầu vào; danh tính người xem là một phần của khóa đọc |
+
+## FE-FUNCTION-7 — Tệp route
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Mọi `page.tsx` | `const AuthenticationRoute = () => <AuthenticationPage {...{}} />` rồi `export default AuthenticationRoute` — route không đưa ra quyết định vẽ nào |