@cyberskill/design 1.1.1 → 1.3.8

package/docs/vi/conventions.md

@@ -4,7 +4,7 @@ Cho người và agent *mở rộng hệ thống này*. (Consumer: đọc `SKILL
 
 ## Quy tắc expansion
 
-**Khi bất kỳ thứ gì lớn lên, mọi thứ cập nhật trong cùng một change.** Element/variant, icon, component, token role, ngôn ngữ, hoặc pattern template mới phải lan tới: tokens/source → specimen cards (guidelines + card nhóm component) **và trang guideline liên quan** → bộ ba hợp đồng component (`.jsx` + `.d.ts` + `.prompt.md`) → **mọi** template (tweak enum và map) → Storybook toolbar / Atomic View → docs (đếm README, SKILL, **và mọi tài liệu liên quan change chạm** — kit README, registry, contrast report regen sau đổi token). **Chỉ bump `VERSION` khi có chỉ thị owner; không maintain file changelog** — version là 1.1.0 (post-LAUNCH). Continuity là git history cộng **Release Notes** curated (`docs/release-notes.md` / Storybook). Gate mọi expansion bằng compiler check **và grep enum/list cũ** — không ship nửa lan. Ranh giới phạm vi đã ghi (doctrine, không phải lỗ): trang UI-kit giữ tái tạo Thổ pixel-faithful (trục demo ở Storybook toolbar và Atomic View); mọi template bilingual EN·VN và mặc định tiếng Anh (collateral client/media giữ English-primary), và biến thể ngôn ngữ render **tách hoàn toàn** — xem decision log.
+**Khi bất kỳ thứ gì lớn lên, mọi thứ cập nhật trong cùng một change.** Element/variant, icon, component, token role, ngôn ngữ, hoặc pattern template mới phải lan tới: tokens/source → specimen cards (guidelines + card nhóm component) **và trang guideline liên quan** → bộ ba hợp đồng component (`.jsx` + `.d.ts` + `.prompt.md`) → **mọi** template (tweak enum và map) → Storybook toolbar / Atomic View → docs (đếm README, SKILL, **và mọi tài liệu liên quan change chạm** — kit README, registry, contrast report regen sau đổi token). **`VERSION` auto-bump khi push lên `main`** (Conventional Commits); owner vẫn có thể force bump. **Không maintain file changelog** — đã LAUNCH ở **1.1.0**; pin theo `VERSION`. Continuity là git history cộng **Release Notes** curated (`docs/release-notes.md` / Storybook). Gate mọi expansion bằng compiler check **và grep enum/list cũ** — không ship nửa lan. Ranh giới phạm vi đã ghi (doctrine, không phải lỗ): trang UI-kit giữ tái tạo Thổ pixel-faithful (trục demo ở Storybook toolbar và Atomic View); mọi template bilingual EN·VN và mặc định tiếng Anh (collateral client/media giữ English-primary), và biến thể ngôn ngữ render **tách hoàn toàn** — xem decision log.
 
 ## Bốn trục
 
@@ -16,11 +16,11 @@ Mọi bề mặt render resolve bốn scope trực giao — không bao giờ mã
 | **Language** | `lang` / Language tweak | copy EN · VI | registry component + props template |
 | **Style** | `data-cs-style` (tuỳ chọn; vắng ≡ `liquid-glass`) | pack vật liệu bề mặt | `tokens/styles.css` |
 
-Pack Style duy nhất hiện nay là **liquid-glass**. Bất biến dưới mọi trục: anchors Umber/Ochre, voice, họ chữ, màu semantic status, vòng focus Ochre 3px, sàn APCA, target ≥44px.
+Pack Style duy nhất hiện nay là **liquid-glass**. Bất biến dưới mọi trục: anchors Umber/Ochre, voice, họ chữ, màu semantic status, chỉ báo focus ghép (contour text-primary + halo ochre), sàn APCA, target ≥44px.
 
 ## Ngữ pháp đặt tên
 
-- Tokens: `--cs-<layer>-<role>[-<state>]` (`--cs-color-text-muted`). Layer role element: `--cs-accent-*` (hợp đồng 9-token — xem header `tokens/elements.css`).
+- Tokens: `--cs-<layer>-<role>[-<state>]` (`--cs-color-text-muted`). Layer role element: `--cs-accent-*` (hợp đồng 10-token gồm `--cs-accent-on-strong` — xem header `tokens/elements.css`).
 
 - Classes: `.cs-<block>[-<part>][--modifier]`. Data attributes: `data-theme`, `data-cs-element`, `data-cs-variant`, `data-cs-style`.
 
@@ -36,9 +36,9 @@ Pack Style duy nhất hiện nay là **liquid-glass**. Bất biến dưới mọ
 
 **Template mới** — `templates/<slug>/<Slug>.dc.html` với `<!-- @template name description -->` đầu tiên; `ds-base.js` giữ single-entry (`styles.css` thôi — rebind một dòng đã validate end-to-end Th7 2026 từ path sâu hơn; scaffold test đã gỡ) và publish alias độc lập-id `window.CyberSkillDS` lúc bundle load, nên mount DS component qua `component-from-global-scope="CyberSkillDS.…"` — **không bao giờ** hậu tố `CyberSkillDesignSystem_<projectId>` hardcode (đổi khi re-import; enforce bởi `_audit/namespace-portability.html`); chỉ inline styles; 1–3 tweaks (không plain copy/color — in-place editing phủ những cái đó); printable docs thêm khối print `@page` + `.cs-desk`/`.cs-sheet` và **không** mang dark tweak (print chỉ light).
 
-**Element variant mới** — ở trong envelope oklch của element; đặt 9 token hợp đồng `--cs-accent-*` cộng `--cs-color-text-accent`/`--cs-color-link` (APCA-check cả hai); aurora wash kế thừa từ element qua `.cs-aurora-wash` (chỉ override class rule nếu variant thật sự cần ảnh riêng); đối tác gradient (`grad-b`) phải theo Tương sinh.
+**Element variant mới** — ở trong envelope oklch của element; đặt 10 token hợp đồng `--cs-accent-*` (gồm `--cs-accent-on-strong` ≥4.5:1 trên `-strong`) cộng `--cs-color-text-accent`/`--cs-color-link` (APCA-check cả hai); aurora wash kế thừa từ element qua `.cs-aurora-wash` (chỉ override class rule nếu variant thật sự cần ảnh riêng); đối tác gradient (`grad-b`) phải theo Tương sinh.
 
-**Ship check** — chạy compiler check đến sạch, rồi chạy `_audit/docs-consistency.html` **và** `_audit/namespace-portability.html` (cả hai phải xanh). Version giữ pin 1.1.1.
+**Ship check** — chạy compiler check đến sạch, rồi chạy `_audit/docs-consistency.html` **và** `_audit/namespace-portability.html` (cả hai phải xanh). Pin theo `VERSION` (auto-bump trên `main`).
 
 ## Decision log (owner duyệt)
 
@@ -52,7 +52,7 @@ Pack Style duy nhất hiện nay là **liquid-glass**. Bất biến dưới mọ
 
 - **Mặt chữ display là một token role, không phải mặc định thứ hai (Th7 2026).** `--cs-font-family-display` ship Space Grotesk (variable 300–700, có subset tiếng Việt) self-host cạnh Be Vietnam Pro và JetBrains Mono, để sản phẩm có mặt chữ tiêu đề — `cyberskill.world` / Lumi — tiêu thụ một role của DS thay vì tự nuôi `@font-face` ngoại lệ riêng. **Không thứ gì trong DS trỏ vào nó**: `--cs-heading-family` vẫn resolve về `--cs-font-family-ui`, mọi template và UI kit không đổi, và một scope chọn dùng qua `.cs-display-face` (`base/typography.css`) — chỉ chuyển `--cs-heading-family`, body copy vẫn ở mặt chữ UI. Space Grotesk không có 800, nên heading weight extrabold clamp về 700 trong family đó (CSS không nhảy sang Be Vietnam Pro vì thiếu weight). Thêm một họ chữ nghĩa là thêm face vào `tokens/fonts.css` **và** file vào `fonts/` **và** entry vào `fonts[]`/`brandFonts[]` của `_ds_manifest.json` — `_audit/font-face-integrity.html` fail nếu một trong ba lệch, và fail nếu family nào thiếu subset tiếng Việt. Điều này không đổi mapping sản phẩm → element nào; `docs/products.md` vẫn khóa.
 
-- Biến thể ngôn ngữ render **tách hoàn toàn**: đổi Language tweak cho artifact một ngôn ngữ đầy đủ — không dịch dở trong heading, label, helper text, footer, hoặc body. Phần bilingual-by-design duy nhất là lockup tên + slogan CyberSkill (`Hiện Thực Hoá Ý Chí · Turn Your Will Into Real`, dạng chuẩn — không bao giờ một nửa lẻ) và khối identity pháp lý A4 (tên pháp lý công ty + khẩu hiệu nhà nước). Mọi thứ khác đổi theo tweak (Th7 2026).
+- Biến thể ngôn ngữ render **tách hoàn toàn**: đổi Language tweak cho artifact một ngôn ngữ đầy đủ — không dịch dở trong heading, label, helper text, footer, hoặc body. Phần bilingual-by-design duy nhất là lockup tên + slogan CyberSkill (`Hiện Thực Hoá Ý Chí · Turn Your Will Into Real`, dạng chuẩn — không bao giờ một nửa lẻ) và khối identity pháp lý A4 (tên pháp lý công ty + khẩu hiệu nhà nước). Mọi thứ khác đổi theo tweak — gồm skip link và eyebrow loại tài liệu (FIND-125). Chuỗi catalog `<title>` / `@template name` giữ tiếng Anh cho chỉ mục template, không phải chrome chế độ ngôn ngữ; `_audit/template-lang-parity.html` che chúng khi quét lexicon rò EN (Th7 2026; follow-up FIND-125).
 
 - **Namespace được resolve, không hardcode** — compiler đặt tên bundle global `window.CyberSkillDesignSystem_<projectId>`, và hậu tố 6-hex dẫn từ project id, nên đổi khi hệ thống import vào project khác. Templates đọc alias ổn định `window.CyberSkillDS` mà `ds-base.js` publish lúc bundle load; cards, trang UI-kit, email standalone, và audit harness resolve theo prefix (`window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]`). `_ds_bundle.js`/`_ds_manifest.json` và snapshot đóng băng `_audit/exports/` hợp pháp mang hậu tố thật (chúng *định nghĩa* nó). Enforce bởi `_audit/namespace-portability.html`, quét mọi source index bởi manifest — giữ re-import **zero-touch** (Th7 2026).
 
@@ -70,9 +70,22 @@ Mọi template export; đường đúng phụ thuộc archetype. Mọi đường
 
 **Hành vi font lúc export.** Font brand self-host (`Be Vietnam Pro` UI, `Space Grotesk` display opt-in, mono). PPTX giữ **tên** font brand nhưng không embed file — trên máy không có chúng PowerPoint thay fallback (text Unicode VN được giữ; shape có thể reflow nhẹ). Để hand-off tự chứa đầy đủ, hoặc bảo người nhận cài font, hoặc export với swap web-safe (`fontSwaps:[{from:'Be Vietnam Pro',to:'Arial'}]` — Arial phủ tiếng Việt). Standalone HTML **embed** font (`@font-face` inline từ `styles.css`), nên luôn trung thành offline (Th7 2026).
 
+## Trạng thái dữ liệu bất đồng bộ (FIND-020 — pattern mỏng)
+
+Bề mặt collection sở hữu một fetch phải phân biệt **loading · error · empty · idle-có-dữ-liệu**. Không render thông báo trống trong lúc request đang chạy.
+
+| Trạng thái | Ghép | Ghi chú |
+|---|---|---|
+| **loading** | `Skeleton` (hàng bảng / dòng) + chuỗi status lịch sự | `aria-busy` trên vùng; giữ header cột khi có thể |
+| **error** | `Result status="error"` (hoặc `errorState` tùy chỉnh) | `role="alert"`; host cung cấp thử lại |
+| **empty** | `emptyState` / `EmptyState` | Chỉ sau phản hồi idle thành công với zero rows |
+| **idle** | Các hàng bình thường | Mặc định — bỏ `state` cho specimen tĩnh |
+
+**API tham chiếu:** `DataTable` nhận `state?: "idle" \| "loading" \| "error"` cùng `loadingState` / `errorState` / `loadingRows` tùy chọn. Các component collection khác (`DataGrid`, `TreeTable`, …) nên theo cùng triad khi có async ownership — không invent API loading song song từng bề mặt. Tác vụ dài không dạng bảng vẫn dùng `Spinner` (`role="status"`) hoặc `ProgressBar` với `aria-label` thật; ghép `Skeleton` trang trí (`aria-hidden`) với chuỗi status live.
+
 ## Accessibility (base/a11y.css + component ARIA)
 
-- **Focus rings có hệ thống** — vòng ochre global `:where(:focus-visible)` trong `base/reset.css`, cộng vòng ochre 3px theo component (`components/forms/navigation/controls`). Không bao giờ đặt `outline: none` trên state `:focus-visible` mà không thay vòng (regression menu-item, đã sửa Th7 2026). Soft glow 5px trong `interaction.css` chồng lên vòng 3px, không thay thế.
+- **Focus rings có hệ thống** — global `:where(:focus-visible)` trong `base/reset.css` là chỉ báo **ghép**: contour 2px `text-primary` (≥3:1 trên light và dark) cộng halo ochre 5px. Control wrapper (`SearchField`, `NumberField`, `PromptInput`, `Terminal`, `CommandPalette`) lặp lại qua `:focus-within`. Không bao giờ đặt `outline: none` trên control focusable mà không có vòng thay thế/wrapper.
 
 - **Touch targets** — `base/a11y.css` đảm bảo 44px trên `@media (pointer: coarse)` (tabs, pagination, menu items, stepper, checkbox/radio; segmented 40px trong track đã pad). Mật độ chuột desktop được giữ. `pointer: coarse` dùng có chủ đích thay breakpoint chiều rộng — touch laptop ở 1280px vẫn cần 44px. Button mang khối coarse riêng trong `components.css`.
 

package/docs/vi/decisions.md

@@ -50,12 +50,12 @@ Giữ plan Figma hiện tại. Variables REST API chỉ Enterprise — job ghi *
 
 ## 7. npm publish — live qua Trusted Publishing (OIDC)
 
-**Trạng thái: LAUNCH `@cyberskill/design@1.1.0`; pin hiện tại `@cyberskill/design@1.1.1`; CI publish dùng npm Trusted Publishing; token bị cấm** (Th7 2026; LAUNCH 2026-07-27)
+**Trạng thái: LAUNCH `@cyberskill/design@1.1.0`; pin theo `VERSION` (auto-bump trên main từ Th8 2026); CI publish dùng npm Trusted Publishing; token bị cấm** (Th7 2026; LAUNCH 2026-07-27)
 
 - `package.json` là `private: false`; tên package **`@cyberskill/design`** (`publishConfig.access: public`); `repository.url` khớp repo GitHub này cho provenance.
-- Workflow `.github/workflows/npm-publish.yml`: `id-token: write` + runner GitHub-hosted; **không** đặt `NPM_TOKEN` / `NODE_AUTH_TOKEN` trên bước publish (OIDC). Trusted Publisher trên npm phải liệt kê filename workflow **`npm-publish.yml`** cho `cyberskill-official/design-system`. Soft-skip khi auth / 403 / 404 / EOTP / conflict phiên bản.
+- Workflow `.github/workflows/npm-publish.yml`: `id-token: write` + runner GitHub-hosted; **không** đặt `NPM_TOKEN` / `NODE_AUTH_TOKEN` trên bước publish (OIDC). Trusted Publisher trên npm phải liệt kê filename workflow **`npm-publish.yml`** cho `cyberskill-official/design` (FIND-088). Soft-skip chỉ no-op mong đợi (`already_published` / EPUBLISHCONFLICT, và `missing_secrets` thật sự ngoài GHA). Trên GHA tag / `workflow_dispatch`, **ENEEDAUTH** / **404** / **402** / **403** / **EOTP** fail job; publish thành công được khóa bởi `npm view @cyberskill/design@VERSION` **và** `dist-tags.latest === VERSION` (FIND-020 / FIND-094).
 - **Publishing access** trên npmjs: **Require two-factor authentication and disallow tokens** (Trusted Publishing OIDC vẫn hoạt động; token publish classic / granular bị từ chối). Secret `NPM_TOKEN` dài hạn đã thu hồi.
-- License giữ **UNLICENSED**; phiên bản là **1.1.1**. Dùng đã duyệt ghi tại **`docs/consumer-grant.md`** (sản phẩm portfolio CyberSkill). Cài từ registry một mình không phải license công khai.
+- License giữ **UNLICENSED**; phiên bản theo root `VERSION`. Dùng đã duyệt ghi tại **`docs/consumer-grant.md`** (sản phẩm portfolio CyberSkill). Cài từ registry một mình không phải license công khai.
 
 ## 8. Đóng gói store native — scaffold đã ship; submit tắt
 
@@ -77,7 +77,7 @@ Ghi nhận Th7 2026 — mặc định mở khóa (cập nhật khi bước vận
 
 - **Figma Variables** — giữ Tokens Studio / non-Enterprise (quyết định §3). Soft-skip Variables REST vẫn trung thực.
 - **Code Connect** — **bỏ qua khi còn Figma free**; chỉ xem lại sau Org + library đã publish + `nodeId` thật (quyết định §6). Soft-skip ≠ publish.
-- **npm** — **LAUNCH `@cyberskill/design@1.1.0`**; pin hiện tại **`@cyberskill/design@1.1.1`** (publish qua tag `v*`); CI dùng **Trusted Publishing (OIDC)** qua `npm-publish.yml`; npmjs **disallow tokens**; grant consumer có hiệu lực tại `docs/consumer-grant.md` (quyết định §7). Entry package mặc định là bundler-native `_esm/react.mjs` (React peer); đường browser là `@cyberskill/design/legacy` → `_esm/cs.mjs` (quyết định §10).
+- **npm** — **LAUNCH `@cyberskill/design@1.1.0`**; pin theo `VERSION` (auto-bump trên `main` → tag `v*` → Trusted Publishing); CI dùng **Trusted Publishing (OIDC)** qua `npm-publish.yml`; npmjs **disallow tokens**; grant consumer có hiệu lực tại `docs/consumer-grant.md` (quyết định §7). Entry package mặc định là bundler-native `_esm/react.mjs` (React peer); đường browser là `@cyberskill/design/legacy` → `_esm/cs.mjs` (quyết định §10).
 
 ## 10. Export React bundler-native (Next / SSR)
 
@@ -85,7 +85,7 @@ Ghi nhận Th7 2026 — mặc định mở khóa (cập nhật khi bước vận
 
 - React / react-dom là **peerDependencies** (`^18 || ^19`); entry re-export JSX source (consumer transpile — ví dụ Next `transpilePackages`). Storybook / CI **devDependencies** pin **react@19.2.8** / **react-dom@19.2.8**.
 - Browser / no-build giữ `_esm/cs.mjs` tại `exports["./legacy"]` (CDN self-ensure + `_ds_bundle.js`). React 19 chính thức bỏ UMD — đường CDN load **`umd-react@19.2.8`** (pin SRI) để tạo `window.React` / `window.ReactDOM` cho `_ds_bundle.js`. Cùng pin dùng trong audit HTML, specimen card, UI kit, và runtime `templates/*/support.js` byte-identical.
-- Alias `@cyberskill/design/react` mirror entry mặc định. VERSION là **1.1.1**; republish qua Trusted Publishing sau merge.
+- Alias `@cyberskill/design/react` mirror entry mặc định. VERSION auto-bump trên `main`; republish qua Trusted Publishing khi `version.yml` đẩy tag `v*`.
 - Docs: `docs/consuming.md` (+ VI); gate: `package-exports-integrity` + `test:react-entry`.
 
 ## Việc maintainer (đang mở)
@@ -100,7 +100,7 @@ Theo dõi vận hành — không phải marketing sản phẩm, không phải ba
 
 ~~4. Đường consumer registry đầu tiên~~ — **xong** (Th7 2026): `examples/npm-hello/` cài `@cyberskill/design` cho identity **Lumi** đã khóa; ghi trong `docs/consuming.md` (+ VI) và `docs/release-notes.md`. Nay target **1.1.1** post-LAUNCH.
 
-5. **Drift native + element-pack trên PR là fail-closed** (Th7 2026) — `regenerate-tokens` chạy read-only trên pull request và exit 1 thay vì push; chỉ `regenerate-tokens-push` (main / schedule / thủ công) giữ `contents: write`. Khi PR fail, chạy `npm run tokens:elements && node _audit/ci/generate-native-tokens.mjs` rồi commit packs + natives. Xem `docs/ci-cd.md`.
+5. **Drift native + element-pack trên PR là fail-closed** (Th7 2026; FIND-021 re-gate Th8 2026) — `regenerate-tokens` chạy read-only trên pull request và exit 1 thay vì push; chỉ `regenerate-tokens-push` (main / schedule / thủ công) giữ `contents: write`. Khi PR fail, chạy `npm run tokens:elements && node _audit/ci/generate-native-tokens.mjs` rồi commit packs + natives. Auto-commit từ `regenerate-tokens-push` **không** được dùng `[skip ci]` để tip chạy lại bảng gate (TASK-IMP-008); freshness fail-closed trên PR vẫn là đường chính cho contributor. Thực tế required-check branch protection là NV-18.1 (ngoài repo). Xem `docs/ci-cd.md`.
 
 6. **Shadcn gap / Wave 2** (Th7 2026) — CyberSkill đã phủ ~53/62 primitive shadcn dưới dạng CS-native (forms / overlays / nav / data). Đã ship: pilot `ScrollArea`, `Collapsible`, `AspectRatio`; Wave 2 `AlertDialog` (vs Popconfirm), `Item` row primitive, `NativeSelect`. Phần còn lại của shadcn là non-port có chủ đích (block, Tailwind, Radix CLI). **Không** port những thứ đó — map pattern sang `templates/` + `ui_kits/` hiện có.
 
@@ -112,6 +112,43 @@ Theo dõi vận hành — không phải marketing sản phẩm, không phải ba
 
 Storybook `FullMatrix` bắt buộc khi public primary có ≥1 trong {size enums, variant enums, state keys} (sàn contract ≥28 story). Schema sidecar đã đủ cho template content-hole; template chỉ-axis bỏ qua theo thiết kế. Xem `docs/quality-gates.md` và `docs/storybook.md`.
 
+## 11. Giấy tờ audit — lưu trữ, không xóa
+
+**Lựa chọn owner: archive-don't-delete** (Th8 2026; TASK-IMP-001 / assessment FIND-001)
+
+- Artifact audit UX / AT / chất lượng đã đóng MUST còn tái dựng được từ clone mới. Ưu tiên `_audit/archive/` và/hoặc `docs/audits/` thay vì xóa im lặng.
+- Commit `8646dbf` đã xóa plan UX audit 8/8, AT matrix, README archive, và `TASK-UX-AUDIT-20260808` “không để lại bản ghi vĩnh viễn.” Nội dung được khôi phục tại `docs/audits/ux-audit-2026-08-08/` (kèm pointer `_audit/archive/ux-audit-2026-08-08/`). Các quyết định D1–D6 lịch sử trong plan đã khôi phục **không** ủy quyền xóa audit trail trong tương lai.
+- Chỉnh status-feed / ledger để che công việc audit đã làm nên tránh; nếu commit phải ledger-exempt, ghi exemption và đường dẫn archive trong cùng change.
+- Claim cần provenance (ví dụ “AT complete”, “lawyer-validated”) đòi bản ghi có ngày trong cây hoặc mục quyết định tường minh — không chỉ attestation miệng.
+
+## 12. Kế hoạch tiến hóa 12 tháng — trạng thái adoption
+
+**Lựa chọn owner: partially superseded (gần); giữ plan làm tham chiếu dài hạn** (Th8 2026; TASK-IMP-001 / assessment FIND-002)
+
+Nguồn: `docs/plans/cyberskill-design-system-audit-and-12-month-evolution-plan.md` (ngày audit 2026-07-28). PLAN `task-author` trước đó đã APPROVED (manifest `docs/tasks/.workflow/task-author.design-system-evolution.manifest.json`) nhưng hầu hết artefact chưa land vào `docs/tasks/`.
+
+| Tầm | Trạng thái | Ghi chú |
+|-----|------------|---------|
+| Assessment Phases 0–2 (tập con FIND-001…025) | **Adopted** — hàng đợi improvement CyberOS đang chạy | `TASK-IMP-001`…`TASK-IMP-008` trong `docs/tasks/improvement/`; index `docs/tasks/BACKLOG.md` |
+| Materialize đủ phase 0–6 của plan 12 tháng | **Deferred** | Không tự bung artefact PENDING trong manifest cho tới khi operator triage với tip `1.2.1` / hậu assessment |
+| Việc đã ship ngoài backlog (vd. commit remediation UX 8/8) | **Superseded** với tư cách task sống | Bằng chứng ở `docs/audits/ux-audit-2026-08-08/` + git history; không mở lại trùng trừ khi có finding mới |
+
+Phases 3–5 của **roadmap assessment** (RSC `"use client"`, APG Rating/Tree/Toolbar, CSP, SBOM, …) vẫn là follow-on hoãn — chưa author trong tranche này trừ khi operator yêu cầu.
+
+## 13. Ranh giới Product vs CyberOS
+
+**Lựa chọn owner: hàng rào tường minh** (Th8 2026; assessment area 28 / TASK-IMP-020)
+
+| Lớp | Ship tới consumer? | Nằm ở đâu | Mục đích |
+|-------|---------------------|-------------|---------|
+| **Product design system** | Có — `@cyberskill/design`, cây portable (`styles.css`, `tokens/`, `components/`, `templates/`, gates `_audit/`, host Storybook) | root repo (không-`.cyberos`) | Token, component, template, kit, quality gate xác định |
+| **CyberOS orchestration** | Không (gitignored / agent kit cài được) | `.cyberos/`, `docs/tasks/`, BRAIN dưới `.cyberos/memory/` | Vòng đời task, cổng HITL, agent entry, workflow ship-tasks |
+
+Quy tắc:
+- Tiêu chí chấp nhận product không được đòi `.cyberos/` có mặt cho consumer hoặc cho `npm` publish.
+- Agent vận hành repo này theo `.cyberos/AGENT-ENTRY.md`; người ship DS theo `docs/release-runbook.md`.
+- Không chuyển token/component product vào `.cyberos/`; không publish orchestration CyberOS như một phần của gói npm.
+
 ## Cách đổi một quyết định
 
 Sửa dòng **Lựa chọn owner** tại đây. Người triển khai nối lại CI và docs liên quan trong cùng một change.

package/docs/vi/deploy.md

@@ -48,11 +48,15 @@ Nếu host dưới **domain khác**, đổi absolute URL trong các meta tag cho
 
 **Có Storybook tại `/`:** chạy `npm run build:site` trên host hoặc CI, rồi serve `.vercel-static/` làm webroot. Cấu hình cùng redirect như `vercel.json` (`/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*` → `/`) nếu host hỗ trợ.
 
-Ví dụ Nginx (`.vercel-static` làm `root`):
+Ví dụ Nginx (`.vercel-static` làm `root`) — **cùng security headers với `vercel.json`** (FIND-019):
+```nginx
 server {
   server_name design.cyberskill.world;
   root /var/www/design-system/.vercel-static;
   index index.html;
+  add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; font-src 'self' data:; img-src 'self' data: blob:; connect-src 'self'; frame-src 'self'; worker-src 'self' blob:; base-uri 'self'; form-action 'self'" always;
+  add_header X-Content-Type-Options "nosniff" always;
+  add_header Referrer-Policy "strict-origin-when-cross-origin" always;
   location = /dashboard { return 301 /; }
   location = /dashboard/ { return 301 /; }
   location = /dashboard.html { return 301 /; }
@@ -60,8 +64,11 @@ server {
   location = /playground { return 301 /; }
   location /playground/ { return 301 /; }
 }
+```
 Path portable vẫn là file thật (`guidelines/atomic-view.html`, `_audit/run.html`, `styles.css`, v.v.). Storybook sở hữu `/` và `/index.html`.
 
+**Netlify / Cloudflare Pages / tương tự:** file `_headers` ở root (và `public/_headers`) mirror cùng ba header cho host đọc `_headers` kiểu Netlify. Giữ khớp `vercel.json`.
+
 ## Checklist sau deploy
 1. Mở `/` — xác nhận Storybook load (không 404, directory listing, hay shell dashboard cũ).
 2. Mở `/_audit/run.html` — để board chạy xong, xác nhận mọi fast gate pass trên bản *đã deploy* (CDN cache, MIME type, hoặc file thiếu có thể lộ ở đây dù check local sạch).
@@ -86,12 +93,16 @@ Sau mỗi deploy production:
 
 ## Ghi chú Content-Security-Policy
 
-Static hosting có thể ship CSP chặt. Allowance điển hình cho hệ thống này:
-- `script-src 'self' https://unpkg.com` nếu load React từ CDN cho Atomic View
-- `font-src 'self'`
+CSP chuẩn nằm trong `vercel.json` và được mirror ở `_headers` + snippet nginx ở trên (FIND-015 / FIND-019). Policy hiện tại:
+
+`default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; font-src 'self' data:; img-src 'self' data: blob:; connect-src 'self'; frame-src 'self'; worker-src 'self' blob:; base-uri 'self'; form-action 'self'`
 
-- `img-src 'self' data:`
-Ưu tiên self-host React cạnh `_ds_bundle.js` cho cài air-gapped.
+Lý do:
+- **Đã bỏ `unsafe-eval`** — React vendored local; Storybook static không cần `eval` toàn site.
+- **Đã bỏ CDN script/connect** (`unpkg.com`, `cdnjs.cloudflare.com`) — local-first React / `_ds_bundle.js`.
+- **Giữ `unsafe-inline`** — shell Storybook vẫn emit inline script/style; migrate nonce/hash là follow-on.
+- Ưu tiên self-host React cạnh `_ds_bundle.js` cho cài air-gapped.
+- Header thật trên production đã xác nhận 2026-08-09 qua `curl -sSI https://design.cyberskill.world/` (OQ-003 đóng — xem `docs/audits/nv-rendered-inrepo-2026-08-09.md`).
 
 ## OG đa domain
 

package/docs/vi/quality-gates.md

@@ -2,9 +2,9 @@
 
 Mọi quality gate deterministic trong hệ thống, nó assert gì, tiêu chí pass, hard hay advisory, và chạy ở đâu.
 
-**Gate chạy ở đâu.** *Fast board CI* = job `fast-gates` trong `.github/workflows/design-system-gates.yml`, serve repo và điều khiển `_audit/run.html` headless qua `_audit/ci/run-gates.mjs` (mọi push/PR + nightly + thủ công) — hàng board mới được nhận tự động. Hai gate thêm chạy standalone như *merge blocker* (job `docs-consistency-blocker`, qua `_audit/ci/run-single-gate.mjs`). *Whole-set CI* = job `whole-set-audits` (mọi push/PR + nightly — quyết định B của owner). *Unit test* = `npm run test:unit` trong job `unit-tests` (Node thuần, không trình duyệt). *Node pre-checks* = job `node-prechecks` (authority không trình duyệt: bundle freshness, DESIGN.md freshness) cộng job `token-provenance`. Mọi browser gate publish verdict global (`window.__*`) mà headless runner đọc.
+**Gate chạy ở đâu.** *Fast board CI* = job `fast-gates` trong `.github/workflows/design-system-gates.yml`, serve repo và điều khiển `_audit/run.html` headless qua `_audit/ci/run-gates.mjs` (mọi push/PR + nightly + thủ công) — hàng board mới được nhận tự động. Hai gate thêm chạy standalone như *merge blocker* (job `docs-consistency-blocker`, qua `_audit/ci/run-single-gate.mjs`). *Whole-set CI* = job `whole-set-audits` (mọi push/PR + nightly — quyết định B của owner). *Unit test* = `npm run test:unit` trong job `unit-tests` (Node thuần, không trình duyệt). *Node pre-checks* = job `node-prechecks` (authority không trình duyệt: bundle freshness, DESIGN.md freshness, styles.min.css + contrast-report freshness, manifest coverage) cộng job `token-provenance`. *Storybook CI* = job `storybook-build` (`build:storybook` + freshness `--require`). Mọi browser gate publish verdict global (`window.__*`) mà headless runner đọc.
 
-## Fast board — 34 gates trong `_audit/run.html`
+## Fast board — 40 gates trong `_audit/run.html`
 
 Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở rộng style): [`docs/vi/benchmark-rubric.md`](benchmark-rubric.md).
 
@@ -13,12 +13,18 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 | Contrast guard | `_audit/contrast-guard.html` | Không base rule sơn umber trên bề mặt themeable mà thiếu dark override; mọi cặp text×surface semantic ghi điểm light và dark | 0 rule không shield và 0 cặp fail (`__contrastguard`) | Hard | Fast board CI |
 | Axes guard | `_audit/axis-guard.html` | Không live source đưa lại bề mặt sản phẩm Expression/Density đã nghỉ | 0 hit trên source index bởi manifest (`__axisguard`) | Hard | Fast board CI |
 | Manifest CSS paths | `_audit/manifest-css-guard.html` | Mọi entry `globalCssPaths` của `_ds_manifest.json` tồn tại như raw CSS; mọi `@import` của `styles.css` được liệt kê | 0 thiếu / 0 chưa liệt kê (`__cssguard`) | Hard | Fast board CI |
-| Docs consistency | `_audit/docs-consistency.html` | Mọi claim đếm trong README/SKILL/llms.txt khớp compiler manifest; claim số card trong prose audit (`_audit/index` / README / namespace-portability) khớp `manifest.cards`; `VERSION` + `package.json` pin 1.1.1; không tham chiếu changelog-file; blacklist stale-phrase (suite/pack count đã gỡ trong audit Th7 2026) sạch trên README/SKILL/llms + `docs/*.md` (ghi chú lịch sử dưới `_audit/archive/` không được quét); `DESIGN.md` tồn tại với front-matter version = `VERSION`; routing agent trung thực — Claude path cite `_esm/cs.mjs` + bundle prefix; Stitch path cấm `*.dc.html` làm SoT; tên package `@cyberskill/design` | 0 claim lệch, 0 blacklist hit, pin + stamp + routing nguyên (`__docs`) | Hard | Fast board CI + merge blocker |
+| Docs consistency | `_audit/docs-consistency.html` | Mọi claim đếm trong README/SKILL/llms.txt khớp compiler manifest; claim số card trong prose audit (`_audit/index` / README / namespace-portability) khớp `manifest.cards`; `VERSION` semver và `package.json` khớp (LAUNCH 1.1.0; auto-bump trên main); không tham chiếu changelog-file; blacklist stale-phrase sạch trên README/SKILL/llms + `docs/*.md`; `DESIGN.md` stamp = `VERSION`; routing agent trung thực; doctrine↔source — 10 role accent (gồm `on-strong`), depth scale đủ, default lang `vi`, breakpoint CSS↔JSON, fallback depth trong `base/` | 0 claim lệch + doctrine parity (`__docs`) | Hard | Fast board CI + merge blocker |
+| Asset-weight budget | `_audit/asset-weight-budget.html` | WebP aurora elemental (`assets/aurora-{tho,hoa,thuy,moc,kim}.webp`) dưới trần hồi quy (≤300 KB/file, ≤1.2 MB cả bộ); PNG aurora legacy thì fail; CSS wash không được trỏ JPEG Thổ | Cả năm dưới trần (`__assetweight`) | Hard | Fast board CI (+ Node twin `test-docs-consistency.mjs`) |
 | Docs language parity | `_audit/docs-lang-parity.html` | Mọi EN `docs/*.md` hướng operator có counterpart `docs/vi/`; VI không phải stub trống/TODO (≥40% độ dài EN); blacklist stale-phrase sạch trên cả EN và VI (ghi chú lịch sử dưới `_audit/archive/` không được theo dõi) | 0 cặp thiếu, 0 stub, 0 blacklist hit (`__docslangparity`) | Hard | Fast board CI |
 | DESIGN.md parity | `_audit/design-md-parity.html` | Root `DESIGN.md` (open-spec Stitch) byte-equals regeneration trong trình duyệt từ `tokens.dtcg.json` + `_ds_manifest.json` + `VERSION` qua `scripts/design-md-lib.mjs` dùng chung; từng hàng token được re-check riêng (số hàng in kèm verdict) | Byte-identical + 0 hàng drift (`__designmd`) | Hard | Fast board CI |
-| Version stamp | `_audit/version-stamp.html` | `package.json`, meta `tokens.json`/`tokens.js`, DTCG `$extensions`, `provenance.json` release + dtcgStamp, front matter `DESIGN.md`, và `_esm/cs.mjs` `export const VERSION` đều bằng `VERSION` (pin 1.1.1) | Cả 9 stamp bằng nhau (`__versionstamp`) | Hard | Fast board CI |
+| Version stamp | `_audit/version-stamp.html` | `package.json`, meta `tokens.json`/`tokens.js`, DTCG `$extensions`, `provenance.json` release + dtcgStamp, front matter `DESIGN.md`, và `_esm/cs.mjs` `export const VERSION` đều bằng `VERSION` (pin theo file; LAUNCH 1.1.0) | Cả 9 stamp bằng nhau (`__versionstamp`) | Hard | Fast board CI |
 | Namespace portability | `_audit/namespace-portability.html` | Không source index bởi manifest hardcode hậu tố bundle project-id của compiler | 0 hậu tố hardcode (`__nsguard`) | Hard | Fast board CI |
-| Token contract | `_audit/token-contract.html` | Cả 15 scope element×variant resolve cả 9 role `--cs-accent-*`; token semantic core resolve | 0 role thiếu, 0 token core thiếu (`__contract`) | Hard | Fast board CI |
+| Artifact head | `_audit/artifact-head.html` | Mọi template artifact có `<title>` và `<html lang>` (chuẩn head qua `ds-base`/compiler) | 0 thiếu title/lang (`__artifacthead`) | Hard | Fast board CI |
+| Overflow @320 | `_audit/responsive-overflow-320.html` | Chiều rộng reflow WCAG 1.4.10: template + kit ở 320px không overflow ngang | 0 bề mặt overflow (`__overflow320`) | Hard | Fast board CI |
+| Light contrast | `_audit/light-contrast.html` | DOM walk light (gương `theme-overflow`): fail WCAG AA leaf-text trên nền solid tái hiện được ngoài `REVIEWED_OK` | 0 fail contrast mở (`__lightcontrast`) | Hard | Fast board CI |
+| No third-party | `_audit/no-third-party.html` | Bề mặt sản phẩm (template · kit · Atomic View) không có origin script/style bên thứ ba; React + Babel có dưới `_vendor/` | 0 hit CDN + vendor có mặt (`__nothirdparty`) | Hard | Fast board CI |
+| Zoom + text-spacing | `_audit/zoom-text-spacing.html` | Fixture chrome đại diện: không tràn ngang ở 640px (proxy 200%) và 320px (proxy 400%); áp dụng text-spacing WCAG 1.4.12 | 0 overflow (`__zoomspacing`) | Hard | Fast board CI |
+| Token contract | `_audit/token-contract.html` | Cả 15 scope element×variant resolve cả 10 role `--cs-accent-*` (gồm `on-strong`); token semantic + doc/focus resolve | 0 role thiếu, 0 token core thiếu (`__contract`) | Hard | Fast board CI |
 | Token pipeline | `_audit/token-pipeline-test.html` | Mọi hằng dẫn từ DTCG xuất hiện nguyên văn trong cả ba target `tokens/native/`; provenance sha-256 khớp nguồn DTCG | 0 hằng drift, hash khớp (`__tokenpipe`) | Hard | Fast board CI |
 | Token format parity | `_audit/token-format-parity.html` | Mọi khai báo `--cs-*` trong `tokens/*.css` bằng mirror trong `tokens.json`, `tokens.js` (ESM deep-equal live), và DTCG (chuỗi ext-css hoặc typed transform) — base `:root` + theme dark/system + 15 pack element + 15 pack dark; 4 duration `_ds_manifest.json` bằng `motion.css` (chặn bug reduced-motion 0ms của compiler) | 0 diff trên mọi scope (`__tokenformat`) | Hard | Fast board CI |
 | DTCG typing | `_audit/dtcg-typing.html` | Mọi leaf `$value` DTCG mang W3C `$type`; mọi `{alias}` resolve (theo chuỗi, không cycle); mọi shadow token là object/array có đủ field layer; byType counts bằng `provenance.json` | 0 untyped / dangling / string shadow (`__dtcgtyping`) | Hard | Fast board CI |
@@ -29,8 +35,8 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 | ESM smoke test | `_audit/esm-smoke-test.html` | `_esm/cs.mjs` import không cần build, re-export mọi component manifest, `VERSION` bằng pin `VERSION` gốc, và Button mount nhận brand token | Export/manifest parity + pin VERSION + kiểm token (`__esm`) | Hard | Fast board CI |
 | Package exports integrity | `_audit/package-exports-integrity.html` | Mọi entry `files` của `package.json` và mọi target `module`/`types`/`style`/`exports` tồn tại; mọi target entry-point được `files` phủ (pack-safe); dual entry — `_esm/react.mjs` (mặc định / `./react`, React peer) + `_esm/cs.mjs` (`./legacy`) — hình ESM và re-export ⊆ export lộ trong header bundle | 0 thiếu / chưa phủ / lạ (`__pkgexports`) | Hard | Fast board CI |
 | Component children | `_audit/component-children-test.html` | Component void-element (Checkbox, Radio, Switch, SearchField, NumberField, Slider, Divider, TextField) mount với child lạc mà không throw React #137 | 0 throw (`__result.anyThrew === false`) | Hard | Fast board CI |
-| Component behavior | `_audit/component-behavior-test.html` | 78 assert tương tác thật — mọi public primary có hợp đồng tương tác người dùng (overlay, form, AI gate, shell, media/copy); primary chỉ hiển thị loại trừ theo thiết kế | 78/78 assert pass (`__behavior`) | Hard | Fast board CI |
-| A11y interactions | `_audit/a11y-gate.html` | Focus management (Dialog/Drawer trap + restore + Escape), roving tabindex, combobox `aria-activedescendant`, hợp đồng role/label, cộng Esc/focus open-state cho Cascader · TreeSelect · Tour · HoverCard · ContextMenu | Mọi assert keyboard/ARIA pass (`__a11y`) | Hard | Fast board CI |
+| Component behavior | `_audit/component-behavior-test.html` | 79 assert tương tác thật — mọi public primary có hợp đồng tương tác người dùng (overlay, form, AI gate, shell, media/copy) cộng toast trên dialog; primary chỉ hiển thị loại trừ theo thiết kế | 79/79 assert pass (`__behavior`) | Hard | Fast board CI |
+| A11y interactions | `_audit/a11y-gate.html` | Focus trap/restore, roving, Mentions APG + Sortable buttons (hard-fail), role/label, open-state Esc | Mọi assert keyboard/ARIA pass (`__a11y`) | Hard | Fast board CI |
 | A11y CSSOM | `_audit/a11y-harness.html` | Mọi control `.cs-*` tương tác đạt floor touch-target đã ghi dưới coarse pointer; focus-ring, reduced-motion, và contrast rule chứng minh trong source CSS | 0 vi phạm floor, mọi source proof tìm thấy (`__a11ycss`) | Hard | Fast board CI |
 | Template schema v2 | `_audit/template-schema-test.html` | Mọi sidecar `content-schema.json` validate theo JSON Schema, mọi slot id khai báo resolve tới `{{ hole }}` thật trong template, và mọi template lộ **content** hole author được đều có sidecar (hole trục/control-flow và tweak boolean được loại trừ — xem `docs/template-schema-v2.md`) | 0 sidecar invalid, 0 slot id treo, 0 template hole-driven thiếu sidecar (`__schemav2`) | Hard | Fast board CI |
 | Support runtime identity | `_audit/support-runtime-identity.html` | Mọi bản `templates/*/support.js` (một mỗi template, 84) byte-identical: sha-256 qua SubtleCrypto, đúng một hash duy nhất, số bản == số template manifest | 1 hash duy nhất, count khớp (`__supportid`) | Hard | Fast board CI |
@@ -50,7 +56,7 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 | Gate | File | Assert gì | Tiêu chí pass | Loại | Chạy ở đâu |
 |---|---|---|---|---|---|
 | Responsive overflow | `_audit/responsive-overflow.html` | Mọi template (84) + 3 UI kit render ở 390 px không horizontal document overflow | 0 bề mặt overflow (`__overflow`) | Hard | Whole-set CI (mọi PR + nightly) |
-| Language overflow | `_audit/language-overflow.html` | Cùng set ép Tiếng Việt: VN áp dụng, không overflow, không clip chữ trong hộp fixed/nowrap | 0 over/clip, 0 VN-not-applied (`__language`) | Hard | Whole-set CI (mọi PR + nightly) |
+| Language overflow | `_audit/language-overflow.html` | Cùng set ép Tiếng Việt: VN áp dụng, không overflow, không clip chữ trong hộp fixed/nowrap, và chuỗi EN built-in đã biết (hint PromptInput, FileUpload, pin DataGrid, …) không rò | 0 over/clip/EN-leak (`__language`) | Hard | Whole-set CI (mọi PR + nightly) |
 | Theme overflow | `_audit/theme-overflow.html` | Cùng set ép dark: dark áp dụng, không document overflow, và không fail WCAG leaf-text solid-bg tái lập được ngoài `REVIEWED_OK` | Dark áp dụng + 0 overflow + 0 contrast mở (`__theme`) | Hard (chỉ near-miss allowlist) | Whole-set CI (mọi PR + nightly) |
 
 ## Node pre-checks (không trình duyệt)
@@ -60,8 +66,12 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 | Token provenance | `_audit/ci/check-token-provenance.mjs` | `tokens/native/` + `tokens/provenance.json` khóa với `tokens/tokens.dtcg.json` (cùng authority drift sha-256 như gate token-pipeline) | Exit 0 khi hash khớp | Hard | CI job `token-provenance` |
 | Bundle freshness (authority) | `_audit/ci/check-bundle-freshness.mjs` | `_ds_bundle.js` đã commit được build từ component source hiện tại — khám phá source đầy đủ (đi `components/`, `ui_kits/`, root sources), nên file mới/xóa cũng bị bắt, hàng trình duyệt không làm được | Exit 0, 0 source drift/mới/xóa | Hard | CI job `node-prechecks` |
 | DESIGN.md freshness | `scripts/generate-design-md.mjs --check` | Root `DESIGN.md` byte-equals regeneration mới từ DTCG + manifest + `VERSION` | Exit 0 khi byte khớp | Hard | CI job `node-prechecks` |
+| styles.min.css freshness | `scripts/flatten-styles.mjs --check` | `dist/styles.min.css` đã commit byte-equals flatten `styles.css` + tokens/base (FIND-026) | Exit 0 khi byte khớp | Hard | CI job `node-prechecks` |
+| contrast-report freshness | `scripts/generate-contrast-report.mjs --check` | Báo cáo contrast EN + VI khớp regeneration từ element packs (FIND-026) | Exit 0 khi byte khớp | Hard | CI job `node-prechecks` |
+| Manifest coverage | `_audit/ci/check-manifest-coverage.mjs` | `templates/` + `.card.html` + startingPoints khớp `_ds_manifest.json` (allowlist: `_vendor`, `schema`, `email-safe`) | Exit 0 | Hard | CI `node-prechecks` + unit |
+| Storybook build + freshness | `npm run build:storybook` + `test-storybook-freshness.mjs --require` | Storybook build trong CI; stamp khớp `stories/` + `.storybook/` (FIND-074 / FIND-075) | Exit 0 | Hard | CI job `storybook-build` |
 
-## Unit tests — `npm run test:unit` (11)
+## Unit tests — `npm run test:unit`
 
 | Test | File | Assert gì | Tiêu chí pass | Loại | Chạy ở đâu |
 |---|---|---|---|---|---|
@@ -74,27 +84,35 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 | Code Connect helpers | `_audit/ci/test-code-connect.mjs` | 105 primaries, helper node-map/render, classifier soft-skip, `figma.config.json` đã commit + `.figma.tsx` traffic cao | Mọi assert pass (exit 0) | Hard | Unit test |
 | Native samples | `_audit/ci/test-native-samples.mjs` | App sample SwiftUI / Compose / Flutter mỗi cái ≥ 3 màn hình, tham chiếu hằng token đã generate, và ship scaffold Fastlane store (submit tắt) | Mọi assert pass (exit 0) | Hard | Unit test |
 | Subtree consume | `_audit/ci/test-subtree-consume.mjs` | Bản copy portable `styles.css` + `base/` + `tokens/` + `fonts/` + `_esm/` + `_ds_bundle.js` (không clone full) vẫn resolve token/font và mount Button qua ESM — đường subtree-copy Stitch/Claude | Mọi assert pass (exit 0) | Hard | Unit test |
-| React entry | `_audit/ci/test-react-entry.mjs` | Dual package exports (`.` / `./react` → `_esm/react.mjs`, `./legacy` → `_esm/cs.mjs`); pin VERSION 1.1.1; peerDeps React; react.mjs không CDN/bundle bridge và re-export khớp header bundle; `generate-react-entry --check` xanh | Mọi assert pass (exit 0) | Hard | Unit test |
+| React entry | `_audit/ci/test-react-entry.mjs` | Dual package exports (`.` / `./react` → `_esm/react.mjs`, `./legacy` → `_esm/cs.mjs`); `package.json` version = `VERSION`; peerDeps React; react.mjs không CDN/bundle bridge và re-export khớp header bundle; `generate-react-entry --check` xanh | Mọi assert pass (exit 0) | Hard | Unit test |
 | Element packs | `_audit/ci/test-element-packs.mjs` | `tokens/elements.css` + mirror JSON/JS/DTCG byte-equal regeneration từ `tokens/element-seeds.json` | `generate-element-packs --check` exit 0 | Hard | Unit test |
+| i18n builtins + doc/font residuals | `_audit/ci/test-i18n-builtins.mjs` | Không literal EN UI cứng ngoài registry; 0 hex doc-palette trong templates; 0 font-size px thô trong `base/` | Exit 0 | Hard | Unit test |
+| Manifest coverage | `_audit/ci/check-manifest-coverage.mjs` | Disk templates/cards/startingPoints ⊆ manifest (`email-safe` allowlist) | Exit 0 | Hard | Unit test |
+| Pack hygiene | `_audit/ci/test-pack-hygiene.mjs` | Tarball loại `docs/tasks|audits|plans|status`; gồm notices + fonts + `_vendor/` (FIND-064) | Exit 0 | Hard | Unit test |
+| CI verdict selftest | `_audit/ci/ci-verdict.mjs --selftest` | Helper annotation soft-skip vs success (FIND-095) | Exit 0 | Hard | Unit test |
 
-Suite `test:unit` được nối vào CI workflow như một phần của hardening Th7 2026 (trước đó chỉ chạy local).
+Suite `test:unit` được nối vào CI workflow như một phần của hardening Th7 2026 (trước đó chỉ chạy local). Storybook freshness chạy trong `storybook-build` với `--require` (không skip trong CI).
+
+## Audit probe suite — `npm run test:audit-probe`
+
+Entry thúc đẩy cho proxy audit UX (`_audit/ci/audit-probe-suite.mjs`): suite unit + light-contrast + overflow 320 + language-overflow + zoom/text-spacing. Kiểm tra công nghệ hỗ trợ thủ công vẫn do người review (không bao giờ tự đánh dấu pass).
 
 ## Job sync / phân phối (soft-skip)
 
-Soft-skip nghĩa là job exit 0 kèm report khi secret/plan/API không hoàn tất write thật — **không** có nghĩa Code Connect hay Figma Variables đang live. npm CI publish dùng Trusted Publishing; soft-skip là trung thực auth/conflict. Coi việc maintainer còn lại trong `docs/decisions.md` là danh sách mở (Code Connect hoãn; grant consumer tại `docs/consumer-grant.md`). Storybook `FullMatrix` bắt buộc cho mọi public primary có ≥1 trong {size enums, variant enums, state keys} — helper chung tại `stories/lib/matrix.jsx`.
+Soft-skip nghĩa là job exit 0 kèm report khi secret/plan/API không hoàn tất write thật — **không** có nghĩa Code Connect hay Figma Variables đang live. Soft-skip ghi `$GITHUB_STEP_SUMMARY` và annotation CI riêng (`::error::` trên schedule/main, `::warning::` nơi khác) nên không bao giờ xanh im lặng giống live success (FIND-095). npm CI publish dùng Trusted Publishing; soft-skip chỉ **already-published** và `missing_secrets` thật sự ngoài GHA — auth/404/402 trên GHA release fail closed (xem `docs/release-runbook.md`). Coi việc maintainer còn lại trong `docs/decisions.md` là danh sách mở (Code Connect hoãn; grant consumer tại `docs/consumer-grant.md`). Storybook `FullMatrix` bắt buộc cho mọi public primary có ≥1 trong {size enums, variant enums, state keys} — helper chung tại `stories/lib/matrix.jsx`.
 
 | Job | Script / workflow | Assert gì | Soft-skip khi | Chạy ở đâu |
 |---|---|---|---|---|
 | Figma Variables | `_audit/ci/push-figma-variables.mjs` + job `figma-variables-push` | Secret mở được file; write Variables tùy chọn | Soft-skip khi thiếu secret (cùng trung thực với Code Connect) hoặc non-Enterprise / thiếu scope `file_variables:*` / API **403** sau khi secret đã có. Soft-skip ≠ sync live | Push `main` + thủ công |
 | Code Connect | `_audit/ci/code-connect-publish.mjs` + job `code-connect` | Config + 105 mapping; publish tùy chọn | Thiếu `FIGMA_TOKEN`/`FIGMA_FILE_KEY` hoặc API 403/404/429 | PR + `main` + thủ công |
-| npm publish | `_audit/ci/npm-publish.mjs` + `npm-publish.yml` | `files`/`exports` pack-safe; `npm publish` qua OIDC Trusted Publishing (package disallow tokens) | Auth / 403 / 404 / EOTP / conflict phiên bản | `workflow_dispatch` / tag `v*` |
+| npm publish | `_audit/ci/npm-publish.mjs` + `npm-publish.yml` | `files`/`exports` pack-safe (gồm `_vendor/`); `npm publish` qua OIDC Trusted Publishing (package disallow tokens); sau publish `npm view` version **và** `dist-tags.latest === VERSION` (FIND-094) | Soft-skip: `already_published` / `missing_secrets` ngoài GHA. **Fail trên GHA release:** ENEEDAUTH / 404 / 402 / 403 / EOTP / thiếu trên registry hoặc `latest` sai | `workflow_dispatch` / tag `v*` |
 | Native store | `_audit/ci/native-store-dry-run.mjs` + `native-store.yml` | Scaffold Fastlane + metadata; kiểm secret signed-release | Thiếu `ASC_*` / `PLAY_SERVICE_ACCOUNT_JSON` (submit luôn tắt) | PR + `main` (paths) + thủ công |
 
-## Registry consumer smoke (hard)
+## Registry consumer smoke (fail-closed)
 
 | Job | Script / workflow | Assert gì | Tiêu chí pass | Chạy ở đâu |
 |---|---|---|---|---|
-| npm-hello smoke | `examples/npm-hello` + job `npm-hello-smoke` | Install registry public `@cyberskill/design@1.1.1` resolve đúng tên package + exports (`npm install` + `npm run smoke`; pack proof local nếu VERSION chưa trên registry) | Exit 0 (**hard fail** khi đã publish; soft-skip pack proof nếu VERSION chưa trên registry) | Push/PR path-filtered + nightly + thủ công |
+| npm-hello smoke | `examples/npm-hello` + job `npm-hello-smoke` | Install registry public `@cyberskill/design@$VERSION` resolve đúng tên package + exports (`npm install` + `npm run smoke`) | Exit 0 chỉ khi VERSION có trên registry (**fail-closed**, FIND-087). Pack proof local chỉ khi fork đặt `NPM_HELLO_ALLOW_LOCAL_PACK=true` | Push/PR path-filtered + nightly + thủ công |
 
 ## Hardening Th7 2026 — đã giao
 
@@ -106,3 +124,4 @@ Tám gate audit lên kế hoạch (token-format-parity, version-stamp, support-r
 - **Nội dung template pháp lý** — counsel review instrument; gate chỉ kiểm cấu trúc, cơ chế bilingual, và hình học print.
 - **Baseline pixel-diff** — drift `%` Playwright auto-fail (hard). Sau redesign có chủ đích, làm mới `_audit/baselines/` bằng `pixel-diff.mjs --update` và commit. Trang review side-by-side visual / component vẫn advisory (đánh giá bằng mắt).
 - **Review thiết kế API component** — đặt tên prop và ergonomics do owner review, không assert.
+- **AT thủ công (E1)** — kiểm tra NVDA / VoiceOver (và tương tự) do owner xác nhận; ô trống không phải pass.

package/docs/vi/release-notes.md

@@ -1,6 +1,6 @@
 # Ghi chú phát hành
 
-Điểm nổi bật sản phẩm cho operator — **không** phải git log và **không** phải `CHANGELOG.md`. Hệ thống thiết kế không maintain file changelog. Phiên bản **đã LAUNCH ở 1.1.0**; pin hiện tại **1.1.1** (chỉ thị owner Th7 2026). Bump tiếp theo cần chỉ thị owner rõ. Chân lý kỹ thuật là tip repo; chân lý hướng sản phẩm là trang này (đồng bộ Storybook **Release Notes**).
+Điểm nổi bật sản phẩm cho operator — **không** phải git log và **không** phải `CHANGELOG.md`. Hệ thống thiết kế không maintain file changelog. Phiên bản **đã LAUNCH ở 1.1.0**; **pin theo `VERSION`** (auto-bump khi push lên `main` từ Conventional Commits; owner vẫn có thể force bump). Chân lý kỹ thuật là tip repo; chân lý hướng sản phẩm là trang này (đồng bộ Storybook **Release Notes**).
 
 ## Patch — `@cyberskill/design@1.1.1`
 
@@ -45,5 +45,5 @@ Token CSS, DTCG (`tokens/tokens.dtcg.json`), và mirror SwiftUI / Compose / Flut
 ## Những gì chúng ta không bao giờ ship
 
 - Root **`CHANGELOG.md`** (cấm bởi doctrine và docs-consistency)
-- Bump VERSION mà không có quyết định owner rõ
+- Root CHANGELOG (vẫn cấm) — bump VERSION giờ do workflow auto trên `main`; owner vẫn có thể force
 - Storybook như dependency consumer

package/docs/vi/release-runbook.md

@@ -0,0 +1,78 @@
+# Runbook phát hành (chuẩn)
+
+Một trang về cách một bản phát hành diễn ra và cách biết nó đã thành công. Gộp các vùng 21/23. Chi tiết liên quan: `docs/ci-cd.md`, `docs/deploy.md`, `docs/decisions.md` §7 / §13.
+
+## Kích hoạt
+
+| Đường | Khi nào |
+|------|------|
+| **Tự động** | Push lên `main` với Conventional Commits → `version.yml` bump `VERSION`, stamp artifact, commit `chore(release): X.Y.Z`, tag `vX.Y.Z` |
+| **Ép** | Trailer `Release-As: X.Y.Z` trên commit, hoặc `workflow_dispatch` trên `version.yml` với một level |
+| **Publish thủ công** | `workflow_dispatch` trên `npm-publish.yml` (cũng chạy trên tag `v*`) |
+
+Không bao giờ push/deploy/merge nếu không có chỉ thị operator tường minh khi vận hành như agent.
+
+## Những gì chạy (happy path)
+
+```
+main push (feat/fix/…)
+  → version.yml  (bump VERSION + stamp + bundle + tag vX.Y.Z)
+  → npm-publish.yml  (OIDC Trusted Publishing; sau publish kiểm version + dist-tags.latest)
+  → Vercel (host)  (build:site → .vercel-static; headers từ vercel.json)
+  → sbom.yml trên tag  (artifact CycloneDX)
+```
+
+Scorecard chạy theo lịch tuần + push `main` (`.github/workflows/scorecard.yml`).
+
+## Tín hiệu thành công
+
+1. GitHub Actions: `version` xanh; `npm-publish` xanh (**không** soft-skip) với registry presence **và** `dist-tags.latest === VERSION` (FIND-094).
+2. `npm view @cyberskill/design version` **và** `npm view @cyberskill/design dist-tags.latest` đều bằng root `VERSION`.
+3. `npm-hello-smoke` xanh trên tip (cài registry fail-closed của VERSION đó — FIND-087).
+4. Production: `/` là Storybook; `/VERSION` là semver thuần; bảng nhanh `/_audit/run.html` xanh.
+5. Artifact: `cyclonedx-sbom` trên lần chạy tag; Scorecard SARIF trên Security / Actions artifacts.
+6. Health sau deploy trong `docs/deploy.md`.
+
+## Tag lịch sử chưa publish (không backfill)
+
+| Tag | Trạng thái | Hành động operator |
+|-----|--------|-----------------|
+| `v1.2.1` | Tag git lịch sử; **không** publish lên npm như `latest` | Để unpublished |
+| `v1.3.0` | Tag git lịch sử; **không** publish lên npm như `latest` | Để unpublished |
+| `v1.3.1` (tip hiện tại) | **Mục tiêu publish** khi operator chỉ thị | Chỉ publish **`1.3.1`** làm `dist-tags.latest` |
+
+**Không** publish `1.2.1` hay `1.3.0` để đóng lệch registry — đóng FIND-102 bằng cách publish **chỉ `1.3.1`** (có cổng operator). npm `latest` có thể vẫn đọc `1.2.0` cho tới khi publish đó land.
+
+## Thất bại / phục hồi
+
+| Triệu chứng | Hành động |
+|---------|--------|
+| `npm-publish` 403 / EOTP / ENEEDAUTH / 404 / 402 trên tag hoặc `workflow_dispatch` | **Fail-closed.** Sửa Trusted Publisher binding cho repo **`cyberskill-official/design`** (FIND-088) / 2FA / OIDC; chạy lại trên tag. Soft-skip **không** được báo success cho các lỗi này. |
+| Soft-skip `already_published` | No-op kỳ vọng — xác nhận registry; đừng coi là success nếu bạn định phát hành bản mới. |
+| Soft-skip `missing_secrets` | Chỉ kỳ vọng **ngoài** GitHub Actions (local). Trên GHA release đây là hard fail. |
+| `version.yml` push soft-warn | Đặt `PUSH_TOKEN` hoặc cho Actions push qua branch protection (xem `docs/ci-cd.md`). |
+| `npm-hello-smoke` đỏ (VERSION thiếu trên registry) | Kỳ vọng cho tới khi publish land (FIND-087). Theo **Sự cố: bản phát hành chưa publish** bên dưới — không đặt `NPM_HELLO_ALLOW_LOCAL_PACK` trên repo chuẩn. |
+| Nightly `design-system-gates` đỏ | GitHub thông báo subscriber workflow mặc định; xem “Cảnh báo job lịch” bên dưới. Chạy lại `workflow_dispatch`. |
+| Deploy Vercel một phần | Chạy lại deploy; theo protocol Health; không bịa claim header live nếu chưa `curl -sSI`. |
+
+## Sự cố: bản phát hành chưa publish (FIND-100 / FIND-101 / FIND-107)
+
+Dùng khi git/`VERSION`/site đi trước npm `dist-tags.latest` (ví dụ tip `1.3.1`, registry vẫn `1.2.0`).
+
+1. **Xác nhận lệch** — `cat VERSION`; `npm view @cyberskill/design version`; `npm view @cyberskill/design dist-tags.latest`; ghi nhận tag git `v1.2.1` / `v1.3.0` / `v1.3.1` là lịch sử vs mục tiêu publish.
+2. **Không** coi soft-skip xanh của `npm-publish` (hay proof pack local xanh của `npm-hello`) là bằng chứng VERSION đã public — smoke fail-closed; lỗi auth publish hard-fail trên GHA.
+3. **Sửa Trusted Publisher** nếu cần — cấu hình npm package phải liệt kê org/repo **`cyberskill-official/design`**, workflow **`npm-publish.yml`**, và đúng environment (FIND-088). Classic `NPM_TOKEN` bị cấm. CI dùng userconfig OIDC sạch (không `_authToken` rỗng từ `actions/setup-node`) để Trusted Publishing đổi token OIDC GitHub.
+4. **Publish có cổng operator** — chỉ sau chỉ thị tường minh: chạy lại `npm-publish.yml` trên tag **`v1.3.1`** (hoặc `workflow_dispatch` tại tip đó). Mục tiêu publish là **chỉ `1.3.1`**; không backfill `1.2.1` / `1.3.0`.
+5. **Xác minh** — `npm view @cyberskill/design@1.3.1 version` và `dist-tags.latest` đều `1.3.1`; chạy lại `npm-hello-smoke` (hoặc chờ lần gates kế) tới xanh.
+6. **Rollback / deprecate (nếu bản xấu đã lên `latest`)** — `npm deprecate @cyberskill/design@<bad> "…"` và/hoặc `npm dist-tag add @cyberskill/design@<good> latest`. npm thường không cho unpublish bản public gần đây — ưu tiên deprecate + retag `latest`. Rollback site/Vercel độc lập (`docs/deploy.md`).
+
+## Cảnh báo job lịch (area 27)
+
+- Cron nightly `0 3 * * *` trên `design-system-gates.yml`.
+- Khi schedule fail, job `notify-schedule-failure` (`needs` mọi job lịch — FIND-108) emit annotation lỗi Actions và fail khi `contains(needs.*.result, 'failure')`, kích hoạt **email native GitHub khi workflow fail** tới watcher repo / actor cuối theo Settings → Notifications.
+- Tuỳ chọn: thêm biến/secret Actions cho Slack webhook sau; không bắt buộc để CI xanh.
+- Operator nên theo dõi badge Actions trong `docs/ci-cd.md` và bật thông báo “Actions” cho workflow fail.
+
+## Product vs CyberOS
+
+Xem `docs/decisions.md` §13. Gói npm và cây portable là sản phẩm; `.cyberos/` chỉ là orchestration.

package/docs/vi/sync.md

@@ -1,6 +1,6 @@
 # Repo ↔ Claude Design — round-trip fidelity & đồng bộ hai chiều
 
-Repo GitHub (`cyberskill-official/design-system`) là **nguồn chân lý**. Session Claude Design là filesystem project tạm — tài liệu này nói cách chúng giữ sync mà không mất việc.
+Repo GitHub (`cyberskill-official/design`) là **nguồn chân lý**. Session Claude Design là filesystem project tạm — tài liệu này nói cách chúng giữ sync mà không mất việc.
 
 ## Repo có khôi phục nguyên hệ thống không?
 
@@ -39,7 +39,7 @@ Diff PR là lưới an toàn — nó hiện đúng những gì đổi kể từ
 ## Hygiene giữ round-trip sạch
 - **`.gitignore`** transient (`uploads/`, `scraps/`, `_audit/exports/`); commit mọi thứ khác, **kể cả `_esm/`** (xem trên — nó là source, không phải build artifact, dù có tiền tố `_`). Compiled `_ds_bundle.js`/manifest được commit cho consumer không có bước build, nhưng kỳ vọng churn — hoặc ignore và để mỗi session regenerate.
 
-- **`VERSION` đã LAUNCH ở 1.1.0; pin hiện tại **1.1.1**** — chỉ bump khi có chỉ thị owner rõ; không maintain file changelog. Continuity là git history; việc maintainer đang mở nằm ở `docs/decisions.md`.
+- **`VERSION` đã LAUNCH ở 1.1.0; pin theo `VERSION`** — auto-bump khi push lên `main` (`.github/workflows/version.yml` → tag `v*` → `npm-publish.yml`); owner vẫn có thể force bump. Không maintain file changelog. Continuity là git history; việc maintainer đang mở nằm ở `docs/decisions.md`.
 
 - **Một nguồn chân lý tại một thời điểm.** Đừng sửa repo và project Claude Design song song rồi push cả hai — pull, làm việc, push, theo thứ tự đó, để repo luôn là điểm merge.
 

package/docs/viewer.html

@@ -58,12 +58,12 @@
 <script>
 const DOCS_EN=[
  ['Start',[['README.md','README'],['SKILL.md','SKILL (agent rules)'],['llms.txt','llms.txt'],['CONTRIBUTING.md','Contributing']]],
- ['Guides',[['docs/consuming.md','Consuming & upgrading (incl. AI-agent quick path)'],['docs/consumer-grant.md','Consumer grant (npm · UNLICENSED)'],['docs/deploy.md','Deploy (Vercel/VPS)'],['docs/template-schema-v2.md','Template content-schema v2'],['docs/conventions.md','Conventions'],['docs/release-notes.md','Release Notes'],['docs/storybook.md','Storybook (product at /)'],['docs/live-hub.md','Live hub (Storybook at /)'],['docs/design-styles.md','Design styles'],['docs/benchmark-rubric.md','Benchmark rubric'],['docs/products.md','Products'],['docs/contrast-report.md','Contrast report'],['docs/figma.md','Figma']]],
+ ['Guides',[['docs/consuming.md','Consuming & upgrading (incl. AI-agent quick path)'],['docs/consumer-grant.md','Consumer grant (npm · UNLICENSED)'],['docs/deploy.md','Deploy (Vercel/VPS)'],['docs/template-schema-v2.md','Template content-schema v2'],['docs/conventions.md','Conventions'],['docs/release-notes.md','Release Notes'],['docs/release-runbook.md','Release runbook'],['docs/storybook.md','Storybook (product at /)'],['docs/live-hub.md','Live hub (Storybook at /)'],['docs/design-styles.md','Design styles'],['docs/benchmark-rubric.md','Benchmark rubric'],['docs/products.md','Products'],['docs/contrast-report.md','Contrast report'],['docs/figma.md','Figma']]],
  ['Maintainers',[['docs/decisions.md','Decisions'],['docs/ci-cd.md','CI/CD automation'],['docs/quality-gates.md','Quality gates'],['docs/sync.md','Git sync & hygiene']]]
 ];
 const DOCS_VI=[
  ['Bắt đầu',[['README.md','README (EN)'],['SKILL.md','SKILL (EN)'],['llms.txt','llms.txt (EN)'],['CONTRIBUTING.md','Contributing (EN)']]],
- ['Hướng dẫn',[['docs/consuming.md','Tiêu thụ & nâng cấp'],['docs/consumer-grant.md','Grant consumer (npm · UNLICENSED)'],['docs/deploy.md','Deploy (Vercel/VPS)'],['docs/template-schema-v2.md','Template schema v2'],['docs/conventions.md','Conventions'],['docs/release-notes.md','Ghi chú phát hành'],['docs/storybook.md','Storybook (sản phẩm tại /)'],['docs/live-hub.md','Live hub (Storybook tại /)'],['docs/design-styles.md','Phong cách'],['docs/benchmark-rubric.md','Rubric benchmark'],['docs/products.md','Sản phẩm'],['docs/contrast-report.md','Báo cáo contrast'],['docs/figma.md','Figma']]],
+ ['Hướng dẫn',[['docs/consuming.md','Tiêu thụ & nâng cấp'],['docs/consumer-grant.md','Grant consumer (npm · UNLICENSED)'],['docs/deploy.md','Deploy (Vercel/VPS)'],['docs/template-schema-v2.md','Template schema v2'],['docs/conventions.md','Conventions'],['docs/release-notes.md','Ghi chú phát hành'],['docs/release-runbook.md','Runbook phát hành'],['docs/storybook.md','Storybook (sản phẩm tại /)'],['docs/live-hub.md','Live hub (Storybook tại /)'],['docs/design-styles.md','Phong cách'],['docs/benchmark-rubric.md','Rubric benchmark'],['docs/products.md','Sản phẩm'],['docs/contrast-report.md','Báo cáo contrast'],['docs/figma.md','Figma']]],
  ['Maintainer',[['docs/decisions.md','Quyết định'],['docs/ci-cd.md','CI/CD'],['docs/quality-gates.md','Quality gates'],['docs/sync.md','Đồng bộ Git']]]
 ];
 let lang=(localStorage.getItem('cs-docs-lang')==='vi')?'vi':'en';