@starci/skills 1.1.0

package/knowledge/grammars/starci/idioms.md

@@ -0,0 +1,120 @@
+# StarCi Core — idioms
+
+An idiom is a composition StarCi reaches for again: a recurring way of putting published Grammar
+renderers together that the owner has already chosen more than once. This file is taste, not law.
+Universal law lives in [knowledge/ui](../../ui/INDEX.md); what each renderer is and owns lives in
+[DNA](DNA.md), generated from the package. Nothing here re-narrates renderer anatomy, and nothing
+here tells anyone to go looking for inspiration: a direction is composed from these idioms plus the
+business shape, and a reference, when the request supplies one, is read through them.
+
+Promotion has one bar: at least two occurrences in the evidence blocks — starci
+`src/components/blocks/dashboard/*` and `src/components/blocks/commerce/ProSubscriptionBlock`, and
+nivo `apps/app/src/components/blocks/auth/AuthenticationPanel`. A composition seen once is recorded
+at the bottom and never composed from. Where the owner has already written down the intent, that
+sentence is quoted from the block's own `classNames.ts`, because it is the owner's word on why the
+shape exists. Every composition cell names only renderers and props the package publishes.
+
+## Joined bands in one flush card
+
+One card, no inner cards: the body is flush, and horizontal rules alone divide it into bands.
+
+| Use when | Grammar composition | Evidence |
+| --- | --- | --- |
+| A dashboard section holds two or more kinds of content that belong to one heading | `SurfaceCard label composition="joined"` around one app `flex flex-col` body whose children are the bands; the card owns the outer boundary and clipping, the app owns `border-t border-separator` between bands | 10 dashboard blocks: `ChangelogList`, `ContinueLearning`, `DailyQuest`, `FeedExplorer`, `JobReadinessWidget`, `OverviewContributions`, `StreakStrip`, `TrendingContents`, `WeeklyChallengeCard`, `WeeklyGoals`. Owner: "Stack full-bleed bands inside one bounded dashboard surface", "Separate stacked dashboard bands without inventing extra vertical space" (`blocks/dashboard/classNames.ts`) |
+| A band is a list of peers | An app `ul`/`div` with `m-0 list-none p-0 divide-y divide-separator`; each row `px-4 pt-3 pb-3 last:pb-4`, so the inset is constant and only the outer bottom edge grows | `ChangelogList`, `DailyQuest` tasks, `JobReadinessWidget` pillars, `WeeklyChallengeCard` finishers, `MyCoursesProgress`, `RecommendedCourses`, commerce benefit grid. Owner: "One divided row inside a flush dashboard list: px-4 always; pb-4 only on the bottom edge" (`blocks/dashboard/classNames.ts`) |
+| An explanatory page section carries prose, art, and a list | Same card, the three as successive bands rather than three cards | `ProSubscriptionBlock` benefits card: intro band, journey band, benefit grid inside one `SurfaceCard label composition={"joined"}` |
+
+## A neutral band opens the card with its summary
+
+The card's one-line answer sits first, on the secondary surface, and is separated from the evidence
+below it — a summary, never a verdict.
+
+| Use when | Grammar composition | Evidence |
+| --- | --- | --- |
+| A card states a measure before it shows the evidence for it | App band `bg-surface-secondary text-foreground px-4 pt-4 pb-3` as the first child of the joined card, then `border-t border-separator` | `JobReadinessWidget` headline, `WeeklyGoals` summary, `WeeklyChallengeCard` countdown, `ProSubscriptionBlock` benefits intro |
+| The band sits between two separators rather than at the top | The same treatment at `px-4 py-3` | `DailyQuest` reward band. Owner: "Neutral band between separators: px-4 always; p-3 on both separator sides vertically" (`blocks/dashboard/classNames.ts`) |
+| The summary is a proven outcome, not a pending promise | Only then does the band take a state colour; an unclaimed promise stays neutral | Owner: "Keep an unclaimed promise neutral; only a proven claimed outcome receives success" (`DailyQuest/classNames.ts`); "Present weekly progress as a neutral summary rather than a state outcome" (`WeeklyGoals/classNames.ts`); [TRUTH-1..4](../../ui/proof/render-truth.md) |
+
+## The card's one action closes the bottom band
+
+A card has at most one onward action, and it lives in its own band against the card's bottom edge —
+never floating inside the content.
+
+| Use when | Grammar composition | Evidence |
+| --- | --- | --- |
+| A card offers one way onward | App band `border-t border-separator px-4 pb-4 pt-3` as the last child, holding one `Button` or `TextAction` | `JobReadinessWidget`, `StreakStrip`, `WeeklyChallengeCard`, `WeeklyGoals`. Owner: "Keep a card's lone action separated at the bottom edge" (`blocks/dashboard/classNames.ts`) |
+| The action is a purchase and must survive a narrow viewport | The same band with `grid grid-cols-1 gap-2`, the `Button variant="primary"` stretched to the band width, and an optional `Text size="xs" tone="muted"` under it | `ProSubscriptionBlock`. Owner: "Full-bleed divider and inset action content for the purchase boundary" (`ProSubscriptionBlock/classNames.ts`) |
+
+## Generated art is a band, not a card
+
+Generated imagery earns a band inside the surface it belongs to. It never becomes a second card, and
+it never gets an inset frame that letterboxes it.
+
+| Use when | Grammar composition | Evidence |
+| --- | --- | --- |
+| The asset is the point of the section | Its own full-bleed band inside the joined card: `border-t border-separator` above, no inset, and an image at `block h-auto w-full` so the generated ratio survives | `ProSubscriptionBlock` journey band. Owner: "The generated journey is its own edge-to-edge joined band; the SurfaceCard owns outer clipping" and "Preserve the generated asset ratio without an inset frame or letterbox" (`ProSubscriptionBlock/classNames.ts`) |
+| The asset is decorative reward or discovery art | `MediaFrame aspect="landscape" fit="contain" treatment="plain"` inside an app band on `bg-accent-soft`, or an accent slab with the art anchored to its trailing edge and `alt=""`/`aria-hidden` | `TrendingContents` media panel — owner: "Keep generated discovery media prominent without becoming a separate card"; `DailyQuest` hero — owner: "The generated quest illustration stays decorative on the hero's trailing edge" |
+
+## Title and one supporting line
+
+Two lines, tightly stacked: what the thing is called, then one muted line that qualifies it. It is
+the most repeated relationship in the whole surface set.
+
+| Use when | Grammar composition | Evidence |
+| --- | --- | --- |
+| Inside a row or cell, where the title is not document structure | `Text size="sm" weight="semibold"` then `Text size="xs" tone="muted"`, stacked at [GAP-1](../../ui/presentation/gap.md) | Dashboard rows and the commerce benefit rows. Owner: "Title and explanation stack for one outcome" (`ProSubscriptionBlock/classNames.ts`) |
+| The title is the surface's own name | `Heading` then `Text size="sm" tone="muted"` | nivo `AuthenticationPanel` header and its notice tree. Owner: "Title and subtitle stay visually coupled" (`AuthenticationPanel/classNames.ts`) |
+| The qualifier belongs above the title | `Text size="xs" tone="muted"` first, then `Text size="md" weight="semibold"` | `ContinueLearning`. Owner: "Keep the supporting kind close to the destination title it qualifies" |
+| Grammar should own the pair | `SurfaceCopyGroup` — the one renderer published for this rhythm | `ProSubscriptionBlock` purchase status |
+
+Counted once per container across the evidence blocks, this pair occurs eight times, seven of them
+hand-built with an app `div`; the inventory and the proposal to give `SurfaceCopyGroup` typed slots
+are in [audits/1.0.1/proposals/copy-group-composite.md](../../../audits/1.0.1/proposals/copy-group-composite.md).
+
+## Pending is the same tree, resting
+
+A loading surface is the finished surface with its content at rest — same card, same bands, same row
+count. It is never a spinner and never a different tree.
+
+| Use when | Grammar composition | Evidence |
+| --- | --- | --- |
+| The block is waiting for its data | `SurfaceCard state={loading ? "pending" : "neutral"}`, a fixed-length array of resting items in place of the real ones, and `isSkeleton` on every `Text` and `Heading` inside | `ChangelogList`, `ContinueLearning`, `DailyQuest`, `JobReadinessWidget`, `OverviewContributions`, `StreakStrip`, `WeeklyChallengeCard`, `WeeklyGoals`, `ProSubscriptionBlock` |
+| An action exists but must not fire yet | The same tree with `Button isDisabled` rather than a removed button, so the layout does not move when data lands | `ProSubscriptionBlock` purchase action |
+| The block has no data at all, or the read failed | A different tree: `SurfaceCard composition="single"` around one `EmptyNotice` with `message`, optional `actionLabel`, and `iconSource` — empty and failed are states, not a resting variant | `ContinueLearning`, `DailyQuest`, `TrendingContents`; [STATE-1](../../ui/composition/state.md) |
+
+## One highlighted card
+
+At most one card in a view wears `isHighlight`, and it is the one thing the reader is meant to do
+next. Highlight is a claim about the task, not decoration.
+
+| Use when | Grammar composition | Evidence |
+| --- | --- | --- |
+| Peers are shown together but one is the intended next step | `SurfaceCard isHighlight={true}` on that one card only; peers keep the same props otherwise, so the difference reads as rank rather than as a different component | `ContinueLearning`, where only the first resume item is highlighted — owner: "The first resumable item is the focal task; later items remain useful but quieter" |
+| The view exists to close one decision | The decision card is the highlighted one and sits in the rail of `PrimaryRailLayout`; everything explanatory stays unhighlighted in `primary` | `ProSubscriptionBlock` plan rail |
+
+## Single-column form stack
+
+Fields, then the status sentence, then one primary submit — one column, one submit, in that order.
+
+| Use when | Grammar composition | Evidence |
+| --- | --- | --- |
+| A step asks for credentials or a code | An app `form` around `flex flex-col gap-4`: `Input` per field with `label`, `placeholder`, `hint`, `errorMessage`, `isError`, `isDisabled`; then the status `Text size="sm" tone="muted" live` (`assertive` for a refusal, `polite` otherwise); then one `Button variant="primary" type="submit" isPending` | nivo `AuthenticationPanel`, both the `details` and `code` steps. Owner: "Credentials and their submit controls form one semantic unit" (`AuthenticationPanel/classNames.ts`) |
+| Secondary ways onward exist | They follow the form as `TextAction size="sm"` in a wrapping row, never as a second `Button variant="primary"` | `AuthenticationPanel` resend/back row and its footer prompt. Owner: "Secondary text actions wrap cleanly instead of overflowing" |
+
+## Seen once, not yet an idiom
+
+Recorded so nobody re-derives them as if they were house style, and so a second occurrence can
+promote them. A direction may not compose from this table; a request that needs one of these shapes
+is a choice for the owner.
+
+| Composition | Where | What a second occurrence would settle |
+| --- | --- | --- |
+| Priced decision rail: `Heading level={2}` beside `Badge tone="accent"`, then price and period as one labelled fact, then the bottom action band | `ProSubscriptionBlock` plan | Whether the price/period pair is the house way to state a recurring charge |
+| `SurfaceAccordionCard depth="top"` carrying secondary explanation with no card of its own around it | `ProSubscriptionBlock` disclosures | Whether disclosure is the house answer for content that must be present but not read |
+| Orientation stack before the first band: breadcrumb, then `SectionHeader composition="context-intro" level={1}`, inside a `max-w-3xl` column | `ProSubscriptionBlock` | Whether a route opens with orientation rather than with its first surface |
+| Provider shortcut above a labelled `Divider`, before the credential form | nivo `AuthenticationPanel` | Whether the shortcut always precedes the form |
+| A leading `IconTile` beside a copy block | `ContinueLearning` | Whether identity art belongs beside copy or above it |
+
+The owner's own proposal records one further shape — a muted supporting line followed by an action —
+at two instances and declines to promote it ("Two instances are not a pattern yet; it stays
+app-owned"). It stays out of this file until the owner says otherwise.

package/knowledge/grammars/starci/idioms.vi.md

@@ -0,0 +1,121 @@
+# StarCi Core — idiom
+
+Idiom là một cách ghép mà StarCi quay lại dùng: một lối lắp các renderer Grammar đã công bố mà chủ sở
+hữu đã chọn hơn một lần. File này là gu, không phải luật. Luật universal nằm ở
+[knowledge/ui](../../ui/INDEX.vi.md); còn mỗi renderer là gì và sở hữu cái gì thì nằm ở
+[DNA](DNA.vi.md), sinh ra từ package. Ở đây không kể lại giải phẫu renderer, và cũng không bảo ai đi
+tìm cảm hứng ở đâu: một định hướng được ghép từ các idiom này cộng với hình dạng nghiệp vụ, còn tham
+chiếu, khi yêu cầu có kèm, được đọc xuyên qua chúng.
+
+Điều kiện để một cách ghép thành idiom chỉ có một: xuất hiện ít nhất hai lần trong các block bằng
+chứng — starci `src/components/blocks/dashboard/*` và
+`src/components/blocks/commerce/ProSubscriptionBlock`, cùng nivo
+`apps/app/src/components/blocks/auth/AuthenticationPanel`. Cách ghép mới thấy một lần được ghi ở cuối
+file và không bao giờ được đem ra ghép. Chỗ nào chủ sở hữu đã tự viết ra ý định thì câu đó được trích
+nguyên từ `classNames.ts` của chính block, vì đó là lời của chủ sở hữu về lý do hình dạng ấy tồn tại.
+Mọi ô composition chỉ gọi tên renderer và prop mà package thực sự công bố.
+
+## Joined bands in one flush card
+
+Một thẻ duy nhất, không thẻ lồng: thân thẻ phẳng, và chỉ có đường kẻ ngang chia nó thành các dải.
+
+| Dùng khi | Cách ghép Grammar | Bằng chứng |
+| --- | --- | --- |
+| Một mục dashboard chứa từ hai loại nội dung trở lên nhưng cùng thuộc một tiêu đề | `SurfaceCard label composition="joined"` bọc một thân `flex flex-col` của app mà các con là các dải; thẻ sở hữu biên ngoài và việc cắt, app sở hữu `border-t border-separator` giữa các dải | 10 block dashboard: `ChangelogList`, `ContinueLearning`, `DailyQuest`, `FeedExplorer`, `JobReadinessWidget`, `OverviewContributions`, `StreakStrip`, `TrendingContents`, `WeeklyChallengeCard`, `WeeklyGoals`. Chủ sở hữu: "Stack full-bleed bands inside one bounded dashboard surface", "Separate stacked dashboard bands without inventing extra vertical space" (`blocks/dashboard/classNames.ts`) |
+| Một dải là danh sách các phần tử ngang hàng | `ul`/`div` của app với `m-0 list-none p-0 divide-y divide-separator`; mỗi hàng `px-4 pt-3 pb-3 last:pb-4`, nên lề trong không đổi và chỉ mép dưới ngoài cùng mới nới ra | `ChangelogList`, dải task của `DailyQuest`, trụ đo của `JobReadinessWidget`, hàng finisher của `WeeklyChallengeCard`, `MyCoursesProgress`, `RecommendedCourses`, lưới quyền lợi bên commerce. Chủ sở hữu: "One divided row inside a flush dashboard list: px-4 always; pb-4 only on the bottom edge" (`blocks/dashboard/classNames.ts`) |
+| Một mục giải thích mang cả chữ, tranh và danh sách | Vẫn một thẻ ấy, ba thứ thành ba dải nối nhau thay vì ba thẻ | Thẻ quyền lợi của `ProSubscriptionBlock`: dải mở đầu, dải tranh hành trình, lưới quyền lợi trong cùng một `SurfaceCard label composition={"joined"}` |
+
+## A neutral band opens the card with its summary
+
+Câu trả lời một dòng của thẻ nằm trước, trên nền phụ, và tách khỏi phần bằng chứng bên dưới — là bản
+tóm tắt, không phải một phán quyết.
+
+| Dùng khi | Cách ghép Grammar | Bằng chứng |
+| --- | --- | --- |
+| Thẻ nêu một số đo trước khi trưng bằng chứng cho số đo ấy | Dải của app `bg-surface-secondary text-foreground px-4 pt-4 pb-3` làm con đầu tiên của thẻ joined, rồi `border-t border-separator` | Dải đầu của `JobReadinessWidget`, dải tóm tắt của `WeeklyGoals`, dải đếm ngược của `WeeklyChallengeCard`, dải mở đầu quyền lợi của `ProSubscriptionBlock` |
+| Dải nằm giữa hai đường kẻ chứ không ở trên cùng | Vẫn cách xử lý ấy nhưng `px-4 py-3` | Dải phần thưởng của `DailyQuest`. Chủ sở hữu: "Neutral band between separators: px-4 always; p-3 on both separator sides vertically" (`blocks/dashboard/classNames.ts`) |
+| Bản tóm tắt là kết quả đã chứng minh, không phải lời hứa còn treo | Chỉ khi đó dải mới nhận màu trạng thái; lời hứa chưa nhận vẫn trung tính | Chủ sở hữu: "Keep an unclaimed promise neutral; only a proven claimed outcome receives success" (`DailyQuest/classNames.ts`); "Present weekly progress as a neutral summary rather than a state outcome" (`WeeklyGoals/classNames.ts`); [TRUTH-1..4](../../ui/proof/render-truth.vi.md) |
+
+## The card's one action closes the bottom band
+
+Một thẻ có nhiều nhất một hành động đi tiếp, và nó nằm trong dải riêng sát mép dưới thẻ — không bao
+giờ trôi nổi giữa nội dung.
+
+| Dùng khi | Cách ghép Grammar | Bằng chứng |
+| --- | --- | --- |
+| Thẻ mở ra một lối đi tiếp | Dải của app `border-t border-separator px-4 pb-4 pt-3` làm con cuối cùng, chứa một `Button` hoặc `TextAction` | `JobReadinessWidget`, `StreakStrip`, `WeeklyChallengeCard`, `WeeklyGoals`. Chủ sở hữu: "Keep a card's lone action separated at the bottom edge" (`blocks/dashboard/classNames.ts`) |
+| Hành động là mua và phải sống được trên màn hình hẹp | Vẫn dải ấy nhưng `grid grid-cols-1 gap-2`, `Button variant="primary"` kéo hết bề ngang dải, và tuỳ chọn một `Text size="xs" tone="muted"` bên dưới | `ProSubscriptionBlock`. Chủ sở hữu: "Full-bleed divider and inset action content for the purchase boundary" (`ProSubscriptionBlock/classNames.ts`) |
+
+## Generated art is a band, not a card
+
+Tranh sinh ra được cấp một dải bên trong chính mặt phẳng mà nó thuộc về. Nó không thành thẻ thứ hai,
+và cũng không bị đóng khung thụt vào để rồi lộ viền đen hai bên.
+
+| Dùng khi | Cách ghép Grammar | Bằng chứng |
+| --- | --- | --- |
+| Bức tranh chính là điều mục ấy muốn nói | Một dải tràn viền riêng bên trong thẻ joined: `border-t border-separator` phía trên, không lề trong, ảnh để `block h-auto w-full` để tỉ lệ gốc còn nguyên | Dải hành trình của `ProSubscriptionBlock`. Chủ sở hữu: "The generated journey is its own edge-to-edge joined band; the SurfaceCard owns outer clipping" và "Preserve the generated asset ratio without an inset frame or letterbox" (`ProSubscriptionBlock/classNames.ts`) |
+| Bức tranh là phần thưởng hoặc gợi mở mang tính trang trí | `MediaFrame aspect="landscape" fit="contain" treatment="plain"` đặt trong dải `bg-accent-soft` của app, hoặc một mảng accent với tranh neo ở mép sau và `alt=""`/`aria-hidden` | Khối tranh của `TrendingContents` — chủ sở hữu: "Keep generated discovery media prominent without becoming a separate card"; hero của `DailyQuest` — chủ sở hữu: "The generated quest illustration stays decorative on the hero's trailing edge" |
+
+## Title and one supporting line
+
+Hai dòng xếp sát nhau: tên của thứ đang nói, rồi một dòng mờ bổ nghĩa cho nó. Đây là quan hệ lặp lại
+nhiều nhất trong toàn bộ tập mặt phẳng.
+
+| Dùng khi | Cách ghép Grammar | Bằng chứng |
+| --- | --- | --- |
+| Ở trong một hàng hay một ô, khi tiêu đề không phải cấu trúc tài liệu | `Text size="sm" weight="semibold"` rồi `Text size="xs" tone="muted"`, xếp chồng ở [GAP-1](../../ui/presentation/gap.vi.md) | Các hàng dashboard và các hàng quyền lợi bên commerce. Chủ sở hữu: "Title and explanation stack for one outcome" (`ProSubscriptionBlock/classNames.ts`) |
+| Tiêu đề là tên của chính mặt phẳng | `Heading` rồi `Text size="sm" tone="muted"` | Phần đầu và cây thông báo của nivo `AuthenticationPanel`. Chủ sở hữu: "Title and subtitle stay visually coupled" (`AuthenticationPanel/classNames.ts`) |
+| Phần bổ nghĩa phải nằm trên tiêu đề | `Text size="xs" tone="muted"` trước, rồi `Text size="md" weight="semibold"` | `ContinueLearning`. Chủ sở hữu: "Keep the supporting kind close to the destination title it qualifies" |
+| Muốn Grammar sở hữu cặp này | `SurfaceCopyGroup` — renderer duy nhất được công bố cho nhịp ấy | Trạng thái mua của `ProSubscriptionBlock` |
+
+Đếm mỗi container một lần trên toàn bộ block bằng chứng, cặp này xuất hiện tám lần, bảy trong số đó
+dựng tay bằng `div` của app; bản kiểm kê và đề xuất cấp slot có kiểu cho `SurfaceCopyGroup` nằm ở
+[audits/1.0.1/proposals/copy-group-composite.md](../../../audits/1.0.1/proposals/copy-group-composite.md).
+
+## Pending is the same tree, resting
+
+Mặt phẳng đang tải chính là mặt phẳng hoàn chỉnh với nội dung nghỉ: cùng thẻ, cùng dải, cùng số hàng.
+Nó không bao giờ là một vòng xoay, cũng không bao giờ là một cây khác.
+
+| Dùng khi | Cách ghép Grammar | Bằng chứng |
+| --- | --- | --- |
+| Block đang đợi dữ liệu | `SurfaceCard state={loading ? "pending" : "neutral"}`, một mảng phần tử nghỉ có độ dài cố định thay cho dữ liệu thật, và `isSkeleton` trên mọi `Text` và `Heading` bên trong | `ChangelogList`, `ContinueLearning`, `DailyQuest`, `JobReadinessWidget`, `OverviewContributions`, `StreakStrip`, `WeeklyChallengeCard`, `WeeklyGoals`, `ProSubscriptionBlock` |
+| Hành động đã có nhưng chưa được phép chạy | Vẫn cây ấy với `Button isDisabled` thay vì gỡ nút đi, để bố cục không nhảy khi dữ liệu về | Hành động mua của `ProSubscriptionBlock` |
+| Block không có dữ liệu nào, hoặc lần đọc thất bại | Một cây khác hẳn: `SurfaceCard composition="single"` bọc một `EmptyNotice` với `message`, `actionLabel` tuỳ chọn và `iconSource` — rỗng và hỏng là state, không phải biến thể nghỉ | `ContinueLearning`, `DailyQuest`, `TrendingContents`; [STATE-1](../../ui/composition/state.vi.md) |
+
+## One highlighted card
+
+Trong một khung nhìn, nhiều nhất một thẻ mang `isHighlight`, và đó là việc người đọc nên làm tiếp
+theo. Highlight là một khẳng định về nhiệm vụ, không phải trang trí.
+
+| Dùng khi | Cách ghép Grammar | Bằng chứng |
+| --- | --- | --- |
+| Các phần tử ngang hàng cùng hiện nhưng một cái là bước kế tiếp có chủ đích | `SurfaceCard isHighlight={true}` chỉ trên đúng thẻ đó; các thẻ còn lại giữ nguyên mọi prop khác, để khác biệt đọc ra là thứ hạng chứ không phải một component khác | `ContinueLearning`, nơi chỉ mục học dở đầu tiên được làm nổi — chủ sở hữu: "The first resumable item is the focal task; later items remain useful but quieter" |
+| Khung nhìn tồn tại để chốt một quyết định | Thẻ quyết định là thẻ được làm nổi và nằm ở rail của `PrimaryRailLayout`; mọi thứ giải thích ở lại `primary` và không làm nổi | Rail gói cước của `ProSubscriptionBlock` |
+
+## Single-column form stack
+
+Các ô nhập, rồi câu trạng thái, rồi một nút gửi chính — một cột, một nút gửi, đúng thứ tự ấy.
+
+| Dùng khi | Cách ghép Grammar | Bằng chứng |
+| --- | --- | --- |
+| Một bước hỏi thông tin đăng nhập hoặc mã | `form` của app bọc `flex flex-col gap-4`: mỗi ô là `Input` với `label`, `placeholder`, `hint`, `errorMessage`, `isError`, `isDisabled`; rồi câu trạng thái `Text size="sm" tone="muted" live` (`assertive` khi là lời từ chối, còn lại `polite`); rồi một `Button variant="primary" type="submit" isPending` | nivo `AuthenticationPanel`, cả bước `details` lẫn bước `code`. Chủ sở hữu: "Credentials and their submit controls form one semantic unit" (`AuthenticationPanel/classNames.ts`) |
+| Có những lối đi tiếp phụ | Chúng đứng sau form dưới dạng `TextAction size="sm"` trong một hàng biết xuống dòng, không bao giờ là một `Button variant="primary"` thứ hai | Hàng gửi lại/quay lại và dòng chân của `AuthenticationPanel`. Chủ sở hữu: "Secondary text actions wrap cleanly instead of overflowing" |
+
+## Seen once, not yet an idiom
+
+Ghi lại để không ai suy ngược chúng thành gu nhà, và để lần xuất hiện thứ hai có thể nâng chúng lên.
+Một định hướng không được ghép từ bảng này; yêu cầu nào cần đúng những hình dạng ấy là một lựa chọn
+dành cho chủ sở hữu.
+
+| Cách ghép | Ở đâu | Lần thứ hai sẽ chốt điều gì |
+| --- | --- | --- |
+| Rail quyết định có giá: `Heading level={2}` cạnh `Badge tone="accent"`, rồi giá và kỳ hạn thành một dữ kiện có nhãn, rồi dải hành động dưới đáy | Gói cước của `ProSubscriptionBlock` | Cặp giá/kỳ hạn có phải cách nhà này nêu một khoản thu định kỳ hay không |
+| `SurfaceAccordionCard depth="top"` mang nội dung giải thích phụ mà không có thẻ nào bọc ngoài | Phần công bố của `ProSubscriptionBlock` | Gấp mở có phải câu trả lời của nhà cho nội dung buộc phải có mà không buộc phải đọc hay không |
+| Khối định hướng trước dải đầu tiên: breadcrumb, rồi `SectionHeader composition="context-intro" level={1}`, trong một cột `max-w-3xl` | `ProSubscriptionBlock` | Một route có mở đầu bằng định hướng thay vì bằng mặt phẳng đầu tiên hay không |
+| Lối tắt qua nhà cung cấp đặt trên một `Divider` có nhãn, trước form thông tin đăng nhập | nivo `AuthenticationPanel` | Lối tắt có luôn đứng trước form hay không |
+| Một `IconTile` dẫn đầu đặt cạnh khối chữ | `ContinueLearning` | Tranh định danh thuộc về bên cạnh chữ hay bên trên chữ |
+
+Chính đề xuất của chủ sở hữu còn ghi một hình dạng nữa — một dòng mờ bổ trợ rồi tới một hành động —
+với hai lần xuất hiện, và từ chối nâng nó lên ("Two instances are not a pattern yet; it stays
+app-owned"). Nó ở ngoài file này cho tới khi chủ sở hữu nói khác.

package/knowledge/grammars/starci/playbook.md

@@ -0,0 +1,36 @@
+# StarCi Core — playbook
+
+Which idioms a business shape asks for, and what a supplied reference is allowed to contribute to
+that answer. The idioms themselves are in [Idioms](idioms.md); what the package publishes is in
+[DNA](DNA.md). A shape not listed here is not forbidden — it is undecided, and an undecided shape is
+a question for the owner, not a guess.
+
+## Shapes
+
+| Business shape | What a supplied reference may contribute | Idiom sequence |
+| --- | --- | --- |
+| Purchase decision page — one offer, one price, one commitment (subscriptions) | Keep: the order of regions (what is read before the price), which single decision dominates, and what folds away instead of competing with it. Never crosses over: page layout, brand, palette, type scale, component anatomy, or any control the reference draws that this Grammar does not publish. | Explanatory column in `primary` of `PrimaryRailLayout`, decision card in `rail`: **Joined bands in one flush card** for the explanation → **A neutral band opens the card with its summary** for its intro line → **Generated art is a band, not a card** for the journey asset → **Title and one supporting line** for each included outcome → **One highlighted card** on the decision itself → **The card's one action closes the bottom band** for the purchase → **Pending is the same tree, resting** across the offer read. Secondary explanation folds away; whether it folds into a disclosure is a `DIRECTION_CHOICE_REQUIRED` (seen once). |
+| Learner dashboard — many peer sections, one intended next step | Keep: which sections exist and their reading order, and which single section is the reader's next action. Never crosses over: grid geometry, card chrome, densities, or a section that would need a renderer this family does not publish. | Per section: **Joined bands in one flush card** → **A neutral band opens the card with its summary** where the section states a measure → **Title and one supporting line** inside every row → **The card's one action closes the bottom band** where a section leads somewhere → **Pending is the same tree, resting** for every read, with `EmptyNotice` for empty and failed. Across the page: **One highlighted card** exactly once, on the resume or next-step section. |
+| Sign-in — one surface, several journeys, one submit per step | Keep: the order of the ways in (shortcut before form, or the reverse), which journeys share one surface, and where the way to the other journey sits. Never crosses over: provider branding, illustration, field chrome, or a social-login row this product does not have a provider for. | **Title and one supporting line** as the surface header (`Heading` + muted subtitle) → **Single-column form stack** per step, one `Button variant="primary" type="submit"` each → **Pending is the same tree, resting** through `isPending` and `isDisabled` rather than a replaced tree → the way onward as `TextAction`, last. Whether the provider shortcut precedes the form is seen once; carry the reference's order and say so. |
+
+## How a direction reads this
+
+1. **Business shape first.** Name the shape and the one outcome the surface exists to produce. The
+   shape selects the idiom sequence; nothing else does.
+2. **Then the reference, if the request supplied one.** A reference contributes region order, which
+   decision dominates, and what folds away. It never contributes layout, brand, palette, or
+   component anatomy — those are already owned, by this family and by
+   [knowledge/ui](../../ui/INDEX.md). A reference that can only be honoured by breaking an idiom is
+   evidence about the reference, not about StarCi.
+3. **Then the idioms**, composed in the order the shape's row gives, each one taken whole: an idiom
+   is a relationship, and half of it is a different shape.
+4. **Then [DNA](DNA.md)**, to confirm every renderer and prop the composition names exists, and to
+   read the gaps in [Family and DNA](family.md) before promising a capability. A composition that
+   needs a recorded gap is not a direction yet.
+
+Anything still open after those four steps is not resolved by preference: it stops with
+`DIRECTION_CHOICE_REQUIRED` and goes to the owner. That includes any shape absent from the table
+above, any composition that appears only in the idioms file's seen-once table, and any point where
+the reference and an idiom disagree.
+
+Owner ruling 2026-09-03 on images: a direction that leaves a region reading empty adds an image made to one claim of the promise, on its own judgement, and records why; it never waits to be asked and never decorates a region the copy and the Grammar objects already carry. `frontend.direction.decide` applies this in its `## Images` table.

package/knowledge/grammars/starci/playbook.vi.md

@@ -0,0 +1,35 @@
+# StarCi Core — playbook
+
+Hình dạng nghiệp vụ nào đòi chuỗi idiom nào, và một tham chiếu được phép góp gì vào câu trả lời ấy.
+Bản thân các idiom nằm ở [Idiom](idioms.vi.md); còn package công bố những gì thì nằm ở
+[DNA](DNA.vi.md). Một hình dạng không có trong đây không phải là bị cấm — nó là chưa được quyết, mà
+chưa được quyết thì hỏi chủ sở hữu, không đoán.
+
+## Các hình dạng
+
+| Hình dạng nghiệp vụ | Tham chiếu được góp gì | Chuỗi idiom |
+| --- | --- | --- |
+| Trang quyết định mua — một gói, một giá, một cam kết (thuê bao) | Giữ: thứ tự các vùng (cái gì được đọc trước giá), quyết định duy nhất nào chiếm ưu thế, và cái gì gấp lại thay vì tranh chỗ với nó. Không bao giờ theo sang: bố cục trang, thương hiệu, bảng màu, thang chữ, giải phẫu component, hay bất kỳ control nào tham chiếu vẽ mà Grammar này không công bố. | Cột giải thích ở `primary` của `PrimaryRailLayout`, thẻ quyết định ở `rail`: **Joined bands in one flush card** cho phần giải thích → **A neutral band opens the card with its summary** cho dòng mở đầu → **Generated art is a band, not a card** cho tranh hành trình → **Title and one supporting line** cho từng quyền lợi → **One highlighted card** cho chính thẻ quyết định → **The card's one action closes the bottom band** cho hành động mua → **Pending is the same tree, resting** suốt lần đọc gói. Nội dung phụ thì gấp lại; gấp bằng disclosure hay không là một `DIRECTION_CHOICE_REQUIRED` (mới thấy một lần). |
+| Dashboard người học — nhiều mục ngang hàng, một bước kế tiếp có chủ đích | Giữ: có những mục nào và đọc theo thứ tự nào, và mục nào là việc kế tiếp của người đọc. Không bao giờ theo sang: hình học lưới, viền thẻ, mật độ, hay một mục đòi renderer mà family này không công bố. | Trong từng mục: **Joined bands in one flush card** → **A neutral band opens the card with its summary** khi mục nêu một số đo → **Title and one supporting line** trong mọi hàng → **The card's one action closes the bottom band** khi mục dẫn đi đâu đó → **Pending is the same tree, resting** cho mọi lần đọc, với `EmptyNotice` cho rỗng và hỏng. Trên toàn trang: **One highlighted card** đúng một lần, đặt ở mục học tiếp hoặc bước kế tiếp. |
+| Đăng nhập — một mặt phẳng, nhiều hành trình, mỗi bước một nút gửi | Giữ: thứ tự các lối vào (lối tắt trước form hay ngược lại), những hành trình nào dùng chung một mặt phẳng, và lối sang hành trình kia nằm ở đâu. Không bao giờ theo sang: thương hiệu nhà cung cấp, tranh minh hoạ, viền ô nhập, hay một hàng đăng nhập mạng xã hội mà sản phẩm này không có nhà cung cấp. | **Title and one supporting line** làm phần đầu mặt phẳng (`Heading` cộng dòng phụ mờ) → **Single-column form stack** cho mỗi bước, mỗi bước đúng một `Button variant="primary" type="submit"` → **Pending is the same tree, resting** qua `isPending` và `isDisabled` chứ không thay cây khác → lối đi tiếp là `TextAction`, đặt cuối. Lối tắt có đứng trước form hay không thì mới thấy một lần; theo thứ tự của tham chiếu và nói rõ ra. |
+
+## Một định hướng đọc file này thế nào
+
+1. **Hình dạng nghiệp vụ trước.** Gọi tên hình dạng và kết quả duy nhất mà mặt phẳng ấy tồn tại để
+   tạo ra. Hình dạng chọn chuỗi idiom; không gì khác chọn thay.
+2. **Rồi mới tới tham chiếu, nếu yêu cầu có kèm.** Tham chiếu góp thứ tự vùng, quyết định nào chiếm
+   ưu thế, và cái gì gấp lại. Nó không góp bố cục, thương hiệu, bảng màu hay giải phẫu component —
+   những thứ đó đã có chủ, là family này và [knowledge/ui](../../ui/INDEX.vi.md). Một tham chiếu chỉ
+   theo được bằng cách phá vỡ một idiom là bằng chứng về tham chiếu, không phải về StarCi.
+3. **Rồi tới các idiom**, ghép theo đúng thứ tự dòng của hình dạng, và lấy trọn từng cái: idiom là
+   một quan hệ, lấy một nửa thì thành hình dạng khác.
+4. **Rồi tới [DNA](DNA.vi.md)**, để xác nhận mọi renderer và prop mà cách ghép gọi tên đều tồn tại,
+   và để đọc bảng gap trong [Family và DNA](family.vi.md) trước khi hứa một năng lực. Cách ghép nào
+   cần tới một gap đã ghi thì chưa phải một định hướng.
+
+Cái gì còn mở sau bốn bước ấy thì không giải bằng sở thích: nó dừng lại với
+`DIRECTION_CHOICE_REQUIRED` và về tay chủ sở hữu. Trong đó có mọi hình dạng vắng mặt ở bảng trên, mọi
+cách ghép chỉ nằm ở bảng "mới thấy một lần" của file idiom, và mọi điểm mà tham chiếu với idiom nói
+ngược nhau.
+
+Chốt của owner ngày 2026-09-03 về hình: hướng nào để lại một vùng đọc lên thấy trống thì tự thêm hình làm theo đúng một claim của lời hứa, tự xét và ghi lý do; không bao giờ chờ được yêu cầu và không bao giờ trang trí vùng mà chữ và Grammar object đã gánh được. `frontend.direction.decide` áp điều này trong bảng `## Images` của nó.

package/knowledge/patterns/be/INDEX.md

@@ -0,0 +1,29 @@
+# Backend code patterns
+
+`knowledge/ui/` decides what the interface must be. `knowledge/patterns/be/` decides how the
+NestJS code behind it is written: which root a file lives under, what a GraphQL unit's files are
+called, how a handler is shaped, which alias an import uses, where a docblock sits relative to a
+decorator, how an exception is declared and where it is mapped to HTTP and GraphQL, and where the
+spec goes. Every rule below was extracted from `starci-academy-backend/src/` by opening files and
+counting; each table cites its sources. Where the code is split, the file records the dominant
+variant with its count instead of legislating. Lint rule names from `@starci/eslint-canon-be` are
+quoted only where the code already follows them.
+
+## Catalog
+
+| Knowledge | What it decides | Rules |
+| --- | --- | --- |
+| [Folder](folder.md) | `features/` versus `modules/`, the file set of one GraphQL unit, where exceptions, entities and tests live | BE-FOLDER-1 … BE-FOLDER-7 |
+| [Naming](naming.md) | Kebab file suffixes, class role suffixes, exception identity, enums, constants, methods | BE-NAMING-1 … BE-NAMING-8 |
+| [Function](function.md) | Handler `process`, message envelope, service and resolver `execute`, constructor injection, helpers | BE-FUNCTION-1 … BE-FUNCTION-8 |
+| [Imports](imports.md) | `@modules`/`@features`/`@tests` aliases, brace style, order, layering direction, banned imports | BE-IMPORTS-1 … BE-IMPORTS-7 |
+| [Comment](comment.md) | Docblock after decorators, responsibility over name, enum member docs, `//` prose, ASCII and `vn-ok` | BE-COMMENT-1 … BE-COMMENT-7 |
+| [Typing](typing.md) | `interface` over `type`, named params, `readonly`, enums, no `any`, GraphQL classes | BE-TYPING-1 … BE-TYPING-7 |
+| [Error](error.md) | `AbstractException` shape, metadata, wrapping, the HTTP filter, the GraphQL interceptor and `formatError` | BE-ERROR-1 … BE-ERROR-7 |
+| [Test](test.md) | Colocated `.spec.ts`, lanes by suffix, direct construction with `as never`, what an assertion proves | BE-TEST-1 … BE-TEST-7 |
+
+## Sources
+
+`D:\Repositories\starci-academy-backend\src\` (4463 non-spec TypeScript files, 875 unit specs,
+7 integration specs), `apps/core/src/app.module.ts` for filter registration, `tsconfig.json`,
+`jest.config.ts`, `eslint.config.mjs`.

package/knowledge/patterns/be/INDEX.vi.md

@@ -0,0 +1,29 @@
+# Mẫu mã nguồn backend
+
+`knowledge/ui/` quyết định giao diện phải là gì. `knowledge/patterns/be/` quyết định mã NestJS
+đứng sau giao diện ấy được viết ra sao: một tệp nằm dưới gốc nào, các tệp của một đơn vị GraphQL
+tên gì, một handler có hình dạng nào, một import dùng alias nào, docblock đứng ở đâu so với
+decorator, một exception được khai báo thế nào và được ánh xạ sang HTTP và GraphQL ở đâu, và spec
+nằm chỗ nào. Mọi luật dưới đây được rút ra từ `starci-academy-backend/src/` bằng cách mở tệp và
+đếm; mỗi bảng dẫn nguồn của nó. Nơi nào mã nguồn chia hai ngả, tệp ghi lại biến thể chiếm ưu thế
+cùng con số thay vì áp đặt. Tên luật lint từ `@starci/eslint-canon-be` chỉ được dẫn ở nơi mã đã
+tuân theo.
+
+## Danh mục
+
+| Tri thức | Quyết định điều gì | Luật |
+| --- | --- | --- |
+| [Thư mục](folder.vi.md) | `features/` so với `modules/`, bộ tệp của một đơn vị GraphQL, nơi đặt exception, entity và kiểm thử | BE-FOLDER-1 … BE-FOLDER-7 |
+| [Đặt tên](naming.vi.md) | Hậu tố tệp kebab, hậu tố vai trò của lớp, danh tính exception, enum, hằng, phương thức | BE-NAMING-1 … BE-NAMING-8 |
+| [Hàm](function.vi.md) | `process` của handler, phong bì thông điệp, `execute` của service và resolver, tiêm qua constructor, helper | BE-FUNCTION-1 … BE-FUNCTION-8 |
+| [Import](imports.vi.md) | Alias `@modules`/`@features`/`@tests`, kiểu ngoặc, thứ tự, chiều phân tầng, import bị cấm | BE-IMPORTS-1 … BE-IMPORTS-7 |
+| [Chú thích](comment.vi.md) | Docblock sau decorator, trách nhiệm thay vì tên, chú thích thành viên enum, câu `//`, ASCII và `vn-ok` | BE-COMMENT-1 … BE-COMMENT-7 |
+| [Kiểu](typing.vi.md) | `interface` thay `type`, tham số có tên, `readonly`, enum, không `any`, lớp GraphQL | BE-TYPING-1 … BE-TYPING-7 |
+| [Lỗi](error.vi.md) | Hình dạng `AbstractException`, metadata, bọc lỗi, bộ lọc HTTP, interceptor GraphQL và `formatError` | BE-ERROR-1 … BE-ERROR-7 |
+| [Kiểm thử](test.vi.md) | `.spec.ts` kề bên, làn theo hậu tố, khởi tạo trực tiếp với `as never`, điều một khẳng định chứng minh | BE-TEST-1 … BE-TEST-7 |
+
+## Nguồn
+
+`D:\Repositories\starci-academy-backend\src\` (4463 tệp TypeScript không phải spec, 875 spec đơn
+vị, 7 spec tích hợp), `apps/core/src/app.module.ts` cho việc đăng ký bộ lọc, `tsconfig.json`,
+`jest.config.ts`, `eslint.config.mjs`.

package/knowledge/patterns/be/comment.md

@@ -0,0 +1,80 @@
+# Comment
+
+This file answers one question: given a backend declaration or statement, does it carry a
+comment, where does it sit, and what does it say?
+
+Sources: `features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`features/api/core/graphql/queries/courses/course/course.handler.ts`,
+`modules/platform/exceptions/errors/abstract.ts`, `errors/courses/challenge-not-found.ts`,
+`modules/platform/exceptions/filters/abstract-exception-http.filter.ts`,
+`modules/databases/postgresql/primary/enums/locale.ts`,
+`modules/api/apollo/server/monolithic/monolithic-apollo-server.module.ts`, `eslint.config.mjs`.
+
+## BE-COMMENT-1 — Every export has a docblock, placed after the decorators
+
+1676 of 2009 non-spec files under `features/api/core/graphql` contain a docblock; lint
+`require-export-jsdoc` is at error. The block sits between the class decorators and `export class`.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Resolver | `@Resolver()\n/**\n * GraphQL entry for adding a course to the current user's shopping cart.\n */\nexport class AddToCartResolver` |
+| Case 2 | Handler | `@CommandHandler(AddToCartCommand)\n@Injectable()\n/**\n * Handler for the addToCart mutation.\n *\n * Idempotently places a \`(user, course)\` row into the cart: …\n */\nexport class AddToCartHandler` |
+| Case 3 | Module | `@Module({ … })\n/** Isolated Nest registration for staging a course in the cart before checkout. */\nexport class AddToCartSingleMutationModule` |
+| Case 4 | Input type | `@InputType({ description: "…" })\n/** Request for the addToCart mutation -- identifies the course to add to the caller's cart. */\nexport class AddToCartRequest` |
+| Case 5 | Undecorated export | directly above: `/** CQRS command carrying the request/user context for the addToCart mutation. */\nexport class AddToCartCommand` |
+| Case 6 | Interceptor | `@Injectable()\n/**\n * Interceptor that wraps resolver result in { data, message, success } and handles errors.\n *\n * @example\n * Use @GraphQLSuccessMessage("Done") on a resolver; …\n */` |
+
+## BE-COMMENT-2 — The docblock states responsibility and invariant, not the name
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Why a field is nullable | `\`data\` … is marked \`nullable: true\` because the transform interceptor sets \`data = null\` on the error path -- a non-nullable field would crash GraphQL and mask the real error instead of surfacing it.` (`AddToCartResponse`) |
+| Case 2 | Why a class exists | `Nest's default filter only maps subclasses of \`HttpException\` to their status code -- \`AbstractException\` extends plain \`Error\`, so without this filter every thrown \`AbstractException\` falls through to a generic 500.` (`AbstractExceptionHttpFilter`) |
+| Case 3 | What must not happen | `Fails the request when the challenge id is unknown -- downstream must not grade a ghost challenge.` (`ChallengeNotFoundException`) |
+| Case 4 | Who throws it | `Thrown by \`AiEntitlementService.consume\` when the user has no remaining allowance in one of the sliding windows, …` |
+| Case 5 | Restated name | `/** Constructor. */` still appears in 27 files (`add-to-cart.handler.ts` among them); lint `no-restated-name-jsdoc` names it as debt, not as the pattern |
+
+## BE-COMMENT-3 — Methods and fields
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Method | `/**\n * Processes the addToCart command.\n * @param command - The command carrying request + authenticated user.\n * @returns The cart row holding the course (created or already present).\n */` |
+| Case 2 | Field | `/** Unique error code for identification */ readonly code: string`; `/** Id of the course the user wants to place in their cart. */ courseId: string` |
+| Case 3 | Interface field with a cross-reference | `/** Enrollment id for the active course (user x course), injected by {@link GraphQLEnrollmentGuard} from the \`x-course-id\` header. … */ enrollmentId?: string` |
+| Case 4 | Generic | `@template TParams - The parameters type.` (`ICQRSHandler`) |
+
+## BE-COMMENT-4 — Enum members are each documented
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | `Locale` | `/** Serve Vietnamese copy; missing Vi falls through to \`fallbackLocale\`. */ Vi = "vi", /** Serve English copy; also the usual \`defaultLocale\` / fallback. */ En = "en"` (lint `require-enum-member-jsdoc`) |
+
+## BE-COMMENT-5 — Line comments are prose about why
+
+9720 `//` lines exist in non-spec `src/`. They sit above the statement, in lowercase sentence
+form, and give the consequence that motivates the code.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A guard | `// reject unauthenticated callers up front -- cart rows are per-user` |
+| Case 2 | A constraint | `// idempotent add: if the (user, course) row already exists, return it as-is --\n// creating a second one would violate UQ_cart_items_user_course` |
+| Case 3 | A scope decision | `// a course the user already OWNS must not be carted -- real enrollment (paid)\n// only, so a trial/preview row (is_enrolled = false) still allows adding to cart` |
+| Case 4 | A hand-off | `// hand off to the command handler which performs the DB work` |
+| Case 5 | Error policy | `// any OTHER error (graphql-js's own execution errors …) is by definition an UNEXPECTED server bug, never the client's fault -- default it to 500 too` |
+| Case 6 | The ` -- ` join | used in 1299 of the 9720 lines; a plain sentence is the majority form |
+
+## BE-COMMENT-6 — Block comments for multi-paragraph reasoning inside a body
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | `course.handler.ts` | `/*\n * EITHER IDENTIFIER ADDRESSES THE SAME OBJECT, because the synchronizer writes both.\n * \`MaterializeAndUploadService\` uploads … It used to refuse anything but a display id, … That reading was wrong about the bucket …\n */` — opens with a capitalised claim, then the evidence, then the corrected history |
+| Case 2 | Config | the `eslint.config.mjs` blocks that record why a rule is at error, with the measured debt (`nợ=0 (296/296)`) |
+
+## BE-COMMENT-7 — What a comment never contains
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Non-ASCII | lint `no-non-ascii-source`, `no-ai-symbol`, `no-emoji`; comments stay ASCII |
+| Case 2 | Vietnamese | lint `no-vietnamese`; a Vietnamese string emitted to clients carries a reason: `[Locale.Vi]: "Thêm khóa học vào giỏ hàng thành công", // vn-ok: vi-locale string emitted to clients` (lint `require-vn-ok-reason`) |
+| Case 3 | A suppression | `eslint-disable-next-line` (lint `no-line-suppression`); exceptions live in config with a comment |
+| Case 4 | A restated name | see BE-COMMENT-2 Case 5 |

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

@@ -0,0 +1,80 @@
+# 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 backend, nó có mang chú thích không,
+chú thích đứng ở đâu, và nói gì?
+
+Nguồn: `features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`features/api/core/graphql/queries/courses/course/course.handler.ts`,
+`modules/platform/exceptions/errors/abstract.ts`, `errors/courses/challenge-not-found.ts`,
+`modules/platform/exceptions/filters/abstract-exception-http.filter.ts`,
+`modules/databases/postgresql/primary/enums/locale.ts`,
+`modules/api/apollo/server/monolithic/monolithic-apollo-server.module.ts`, `eslint.config.mjs`.
+
+## BE-COMMENT-1 — Mọi export có docblock, đặt sau các decorator
+
+1676 trên 2009 tệp không phải spec dưới `features/api/core/graphql` chứa docblock; lint
+`require-export-jsdoc` ở mức error. Khối này nằm giữa các decorator của lớp và `export class`.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Resolver | `@Resolver()\n/**\n * GraphQL entry for adding a course to the current user's shopping cart.\n */\nexport class AddToCartResolver` |
+| Case 2 | Handler | `@CommandHandler(AddToCartCommand)\n@Injectable()\n/**\n * Handler for the addToCart mutation.\n *\n * Idempotently places a \`(user, course)\` row into the cart: …\n */\nexport class AddToCartHandler` |
+| Case 3 | Module | `@Module({ … })\n/** Isolated Nest registration for staging a course in the cart before checkout. */\nexport class AddToCartSingleMutationModule` |
+| Case 4 | Kiểu đầu vào | `@InputType({ description: "…" })\n/** Request for the addToCart mutation -- identifies the course to add to the caller's cart. */\nexport class AddToCartRequest` |
+| Case 5 | Export không decorator | ngay phía trên: `/** CQRS command carrying the request/user context for the addToCart mutation. */\nexport class AddToCartCommand` |
+| Case 6 | Interceptor | `@Injectable()\n/**\n * Interceptor that wraps resolver result in { data, message, success } and handles errors.\n *\n * @example\n * Use @GraphQLSuccessMessage("Done") on a resolver; …\n */` |
+
+## BE-COMMENT-2 — Docblock nêu trách nhiệm và bất biến, không nêu tên
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Vì sao một trường nullable | `\`data\` … is marked \`nullable: true\` because the transform interceptor sets \`data = null\` on the error path -- a non-nullable field would crash GraphQL and mask the real error instead of surfacing it.` (`AddToCartResponse`) |
+| Case 2 | Vì sao một lớp tồn tại | `Nest's default filter only maps subclasses of \`HttpException\` to their status code -- \`AbstractException\` extends plain \`Error\`, so without this filter every thrown \`AbstractException\` falls through to a generic 500.` (`AbstractExceptionHttpFilter`) |
+| Case 3 | Điều không được xảy ra | `Fails the request when the challenge id is unknown -- downstream must not grade a ghost challenge.` (`ChallengeNotFoundException`) |
+| Case 4 | Ai ném nó | `Thrown by \`AiEntitlementService.consume\` when the user has no remaining allowance in one of the sliding windows, …` |
+| Case 5 | Nhắc lại tên | `/** Constructor. */` vẫn xuất hiện ở 27 tệp (`add-to-cart.handler.ts` trong số đó); lint `no-restated-name-jsdoc` gọi tên nó là nợ, không phải mẫu |
+
+## BE-COMMENT-3 — Phương thức và trường
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Phương thức | `/**\n * Processes the addToCart command.\n * @param command - The command carrying request + authenticated user.\n * @returns The cart row holding the course (created or already present).\n */` |
+| Case 2 | Trường | `/** Unique error code for identification */ readonly code: string`; `/** Id of the course the user wants to place in their cart. */ courseId: string` |
+| Case 3 | Trường interface có tham chiếu chéo | `/** Enrollment id for the active course (user x course), injected by {@link GraphQLEnrollmentGuard} from the \`x-course-id\` header. … */ enrollmentId?: string` |
+| Case 4 | Generic | `@template TParams - The parameters type.` (`ICQRSHandler`) |
+
+## BE-COMMENT-4 — Mỗi thành viên enum đều được chú thích
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | `Locale` | `/** Serve Vietnamese copy; missing Vi falls through to \`fallbackLocale\`. */ Vi = "vi", /** Serve English copy; also the usual \`defaultLocale\` / fallback. */ En = "en"` (lint `require-enum-member-jsdoc`) |
+
+## BE-COMMENT-5 — Chú thích dòng là văn xuôi về lý do
+
+9720 dòng `//` tồn tại trong `src/` không kể spec. Chúng đứng trên câu lệnh, viết thường theo dạng
+câu, và đưa ra hệ quả thúc đẩy đoạn mã.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một chốt chặn | `// reject unauthenticated callers up front -- cart rows are per-user` |
+| Case 2 | Một ràng buộc | `// idempotent add: if the (user, course) row already exists, return it as-is --\n// creating a second one would violate UQ_cart_items_user_course` |
+| Case 3 | Một quyết định phạm vi | `// a course the user already OWNS must not be carted -- real enrollment (paid)\n// only, so a trial/preview row (is_enrolled = false) still allows adding to cart` |
+| Case 4 | Một lượt chuyển giao | `// hand off to the command handler which performs the DB work` |
+| Case 5 | Chính sách lỗi | `// any OTHER error (graphql-js's own execution errors …) is by definition an UNEXPECTED server bug, never the client's fault -- default it to 500 too` |
+| Case 6 | Dấu nối ` -- ` | dùng ở 1299 trên 9720 dòng; câu trơn là dạng đa số |
+
+## BE-COMMENT-6 — Chú thích khối cho lập luận nhiều đoạn bên trong thân
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | `course.handler.ts` | `/*\n * EITHER IDENTIFIER ADDRESSES THE SAME OBJECT, because the synchronizer writes both.\n * \`MaterializeAndUploadService\` uploads … It used to refuse anything but a display id, … That reading was wrong about the bucket …\n */` — mở bằng một khẳng định viết hoa, rồi bằng chứng, rồi lịch sử đã sửa |
+| Case 2 | Cấu hình | các khối trong `eslint.config.mjs` ghi vì sao một luật ở mức error, kèm nợ đã đo (`nợ=0 (296/296)`) |
+
+## BE-COMMENT-7 — Thứ một chú thích không bao giờ chứa
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Ký tự ngoài ASCII | lint `no-non-ascii-source`, `no-ai-symbol`, `no-emoji`; chú thích giữ ASCII |
+| Case 2 | Tiếng Việt | lint `no-vietnamese`; một chuỗi tiếng Việt phát ra cho client mang theo lý do: `[Locale.Vi]: "Thêm khóa học vào giỏ hàng thành công", // vn-ok: vi-locale string emitted to clients` (lint `require-vn-ok-reason`) |
+| Case 3 | Tắt luật | `eslint-disable-next-line` (lint `no-line-suppression`); ngoại lệ sống trong cấu hình kèm chú thích |
+| Case 4 | Nhắc lại tên | xem BE-COMMENT-2 Trường hợp 5 |