@cyberskill/design 1.0.0

package/docs/vi/quality-gates.md

@@ -0,0 +1,94 @@
+# Quality gates — tài liệu chuẩn benchmark
+
+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.
+
+## Fast board — 31 gates trong `_audit/run.html`
+
+| Gate | File | Assert gì | Tiêu chí pass | Loại | Chạy ở đâu |
+|---|---|---|---|---|---|
+| 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 |
+| Three-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; `VERSION` + `package.json` pin 1.0.0; 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 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 trong 138 token được re-check | 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, và front matter `DESIGN.md` đều bằng `VERSION` (pin 1.0.0) | Cả 8 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 |
+| 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 |
+| Story coverage | `_audit/story-coverage.html` | Mọi primary bundle export có Atomic View story (`guidelines/atomic-view.html`) | 0 story thiếu (`__storycov`) | Hard | Fast board CI |
+| Consumer smoke test | `_audit/consumer-smoke-test.html` | Đường consumer ngoài hoạt động: `styles.css` + `_ds_bundle.js` mount component thật và brand token tới Button đã render | Mọi assert mount + token pass (`__smoke`) | Hard | Fast board CI |
+| Bundle freshness | `_audit/bundle-freshness.html` | Mọi source ghi trong header `_ds_bundle.js` re-hash khớp sha-256 header (nhân bản trình duyệt của `ci/check-bundle-freshness.mjs`; script Node vẫn là authority CI và còn khám phá file mới); source component manifest ⊆ header | 0 source drift / thiếu (`__bundlefresh`) | Hard | Fast board CI (+ Node authority trong `node-prechecks`) |
+| ESM smoke test | `_audit/esm-smoke-test.html` | `_esm/cs.mjs` import không cần build, re-export mọi component manifest, và Button mount nhận brand token | Export/manifest parity + 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`/`style`/`exports` tồn tại; mọi target entry-point được `files` phủ (pack-safe); `_esm/cs.mjs` hình ESM và re-export `CS.*` ⊆ 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` | 35 assert tương tác thật — toggle, controlled selection, lọc palette, overlay open/close, Form rules, Tree/Splitter/keyboard | 35/35 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 | 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 và mọi slot id khai báo resolve tới `{{ hole }}` thật trong template | 0 sidecar invalid, 0 slot id treo (`__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 |
+| Bilingual parity | `_audit/bilingual-parity.html` | Mọi component trong `components/_i18n/strings.js` có bảng en + vi với key set bằng nhau và không giá trị rỗng | 0 key thiếu/thừa, 0 giá trị rỗng (`__bilingual`) | Hard | Fast board CI + merge blocker |
+| Template language parity | `_audit/template-lang-parity.html` | Quét source tĩnh cả 84 `.dc.html`: en/vi hole-map key set giống và không rỗng (21 map template); nhánh `sc-if` `isEN`/`isVN` cặp (24 branch template); mọi template có language-tweak có cơ chế bilingual; lexicon EN-leak (Unsubscribe · View in browser · Preferences · All rights reserved · Manage subscription · Sent with) không bao giờ xuất hiện ngoài guard `isEN` / map `en`. Instrument VN-first stacked (37 `vn-*` + 3 `doc-*`) miễn leak theo thiết kế — cả hai ngôn ngữ luôn render | 0 key drift, 0 nhánh không cặp, 0 leak (`__langparity`) | Hard | Fast board CI |
+| APCA dark packs | `_audit/apca-dark-preview.html` | Cả 15 pack element×variant giữ mục tiêu APCA ở dark (bright-as-text ≥ 75, accent UI ≥ 60, ink-on-accent ≥ 75, ink-on-tint ≥ 75) | 0 fail hiện tại (`__apcaPreview.currentFail === 0`) | Hard | Fast board CI |
+| Visual baselines | `_audit/visual-diff.html` | Baseline template tồn tại và load được để so sánh side-by-side / overlay | Baseline có; drift đánh giá bằng mắt (`__visualdiff`) | Advisory | Fast board CI |
+| Component baselines | `_audit/component-visual-diff.html` | 12 crop component curated neo các tầng atomic cho so sánh visual | Crop render + baseline có (`__componentVisualDiff`) | Advisory | Fast board CI |
+| Axe smoke | `_audit/axe-smoke.html` | Rule serious/critical của axe-core 4.10.0 (vendored tại `_audit/vendor/axe.min.js`) trên cụm component bilingual đã mount | 0 finding serious/critical (`__axesmoke`) | Hard | Fast board CI |
+| Print smoke | `_audit/print-smoke.html` | Document template khai báo meta print-ownership và hook CSS `@page` mà đường export dựa vào | 0 document thiếu print hook (`__printsmoke`) | Hard | Fast board CI |
+| Pixel CI | `_audit/pixel-ci.html` + `_audit/ci/pixel-diff.mjs` | Baseline curated tồn tại; script Playwright capture so sánh % pixel thật; report gần nhất phải sạch (`drifted[]` rỗng) | Hợp đồng + compare sạch (`__pixelci.pass`); drift hoặc thiếu report → fail | Hard | Fast board CI (bước compare nuôi hàng) + job `pixel-diff` |
+
+## Whole-set audits — mọi template, mọi trục
+
+| 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) |
+| 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)
+
+| Gate | File | Assert gì | Tiêu chí pass | Loại | Chạy ở đâu |
+|---|---|---|---|---|---|
+| 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` |
+
+## Unit tests — `npm run test:unit` (8)
+
+| Test | File | Assert gì | Tiêu chí pass | Loại | Chạy ở đâu |
+|---|---|---|---|---|---|
+| Nav model | `_audit/ci/test-nav-model.mjs` | Logic classify/group của `guidelines/nav-model.js` đã ship hành xử đúng (chạy module thật) | Mọi assert pass (exit 0) | Hard | Unit test |
+| Health/Tokens UI contract | `_audit/ci/test-health-tokens-contract.mjs` | Hợp đồng cấu trúc của entry HTML Health + Tokens giữ | Mọi assert pass (exit 0) | Hard | Unit test |
+| Form paths | `_audit/ci/test-form-paths.mjs` | Helper Form path hành xử đúng (chạy `Form.jsx` đã ship qua dynamic import) | Mọi assert pass (exit 0) | Hard | Unit test |
+| Storybook contract | `_audit/ci/test-storybook-contract.mjs` | Live hub chỉ là Storybook; SB10 ESM main + addon-docs/a11y; CSF đủ cho mọi public primary; Matrix/AllVariants + AllSizes khi có `argTypes.size`; States/Matrix phủ disabled/loading/error/busy; mọi enum size/variant rời rạc được mount; FullMatrix bắt buộc khi ≥2 trục trong {size, variant, state} tồn tại | Mọi assert pass (exit 0) | Hard | Unit test |
+| Figma push helpers | `_audit/ci/test-figma-push-helpers.mjs` | Helper thuần trong `push-figma-variables.mjs` hành xử đúng (không mạng, không secret) | Mọi assert pass (exit 0) | Hard | Unit test |
+| Code Connect helpers | `_audit/ci/test-code-connect.mjs` | 99 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 |
+
+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).
+
+## 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 npm, Code Connect, hay Figma Variables đang live. Coi soft-skip là trung thực tạm thời đến khi các việc maintainer còn lại trong `docs/decisions.md` xong (Code Connect node ID; grant npm / `NPM_TOKEN`). Schema sidecar và Storybook `FullMatrix` lớn theo cơ hội khi primary đã đủ điều kiện — không phải đợt mass-add.
+
+| 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 | Non-Enterprise / thiếu scope `file_variables:*` / API 403 | Push `main` + thủ công |
+| Code Connect | `_audit/ci/code-connect-publish.mjs` + job `code-connect` | Config + 99 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` tùy chọn | Thiếu `NPM_TOKEN` hoặc registry auth/404/403 | `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 |
+
+## Hardening Th7 2026 — đã giao
+
+Tám gate audit lên kế hoạch (token-format-parity, version-stamp, support-runtime-identity, package-exports-integrity, template-lang-parity, dtcg-typing, bundle-freshness, design-md-parity) giờ đã **triển khai** — xem hàng của chúng trong bảng fast-board và Node-pre-check trên. Tất cả nối vào `_audit/run.html`, `_audit/index.html`, workflow CI (`fast-gates` nhận hàng board tự động; `node-prechecks` + `unit-tests` là job mới), và `dashboard.html` (tab Health nhúng `run.html`, nên hàng board hiện ở đó không cần list riêng). Gate docs-consistency mang blacklist stale-phrase (suite/pack count đã nghỉ) + mở rộng stamp `DESIGN.md` mô tả ở hàng của nó. Gate docs-lang-parity khóa gương `docs/vi/`.
+
+## Human-reviewed, không bao giờ tự động hóa
+
+- **Brand voice / copy** — ấm · trực tiếp · trung thực · tôn trọng do người đánh giá, không regex.
+- **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.

package/docs/vi/release-notes.md

@@ -0,0 +1,31 @@
+# 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 giữ cố định **1.0.0**; 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**).
+
+## Storybook tại gốc domain
+
+`design.cyberskill.world/` là site sản phẩm Storybook đầy đủ. Docs, Foundations, Components, Release Notes và Status nằm trong một sidebar. Đường legacy `/dashboard` và `/playground` redirect về `/`.
+
+Consumer portable không đổi: `styles.css`, `_ds_bundle.js`, và `_esm/cs.mjs`. Storybook chỉ là tooling host.
+
+## Quality gate trên Status
+
+Story **Status** nhúng bảng gate nhanh (`_audit/run.html`). Gate cứng fail board khi hỏng; hàng advisory được gắn nhãn rõ và không lật aggregate pass. Mở Status lần đầu sẽ auto-run; dùng **Re-run** khi cần chạy lại.
+
+## Docs và template song ngữ
+
+Docs operator công khai có cặp EN·VI dưới `docs/` / `docs/vi/`. Template giữ bilingual EN·VN với chế độ ngôn ngữ tách hoàn toàn. Chuỗi component resolve từ registry trung tâm.
+
+## Foundations và thư viện CSF
+
+Toolbar Theme × Element × Language khớp template production. Mọi primary công khai có Default + ma trận điều khiển trung thực. Foundations gồm màu, typography, spacing, elevation, motion, và 15 pack Ngũ Hành.
+
+## Token và bản native
+
+Token CSS, DTCG (`tokens/tokens.dtcg.json`), và mirror SwiftUI / Compose / Flutter giữ lockstep qua token pipeline. Text không bao giờ nằm trên `-accent` mid-tone — doctrine APCA được gate enforce.
+
+## Những gì chúng ta không bao giờ ship
+
+- File gốc **`CHANGELOG.md`** (cấm bởi doctrine và docs-consistency)
+- Bump VERSION khi chưa có quyết định tường minh từ owner
+- Storybook như dependency của consumer

package/docs/vi/storybook.md

@@ -0,0 +1,56 @@
+# Storybook — bề mặt sản phẩm tại `/` (host)
+
+Storybook **10** là **site sản phẩm** cho operator trên `design.cyberskill.world` (`/`). Nó vẫn **không** thuộc hợp đồng consumer portable.
+
+## URL
+
+| Ngữ cảnh | Path |
+|---|---|
+| Production | `https://design.cyberskill.world/` |
+| Site đóng gói local | `/` sau `npm run build:site` (serve `.vercel-static/`) |
+| Dev local | `npm run storybook` → http://localhost:6006 |
+| Legacy | `/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*` → `/` |
+
+## Nội dung
+
+- CSF component đầy đủ với **Default + ma trận điều khiển sâu** (`Matrix` / `AllVariants`)
+- **CSF bar (exhaustive khi các trục tồn tại):**
+  - `AllSizes` khi `argTypes.size` tồn tại (token ramp hoặc size số đại diện)
+  - `States` (hoặc subsection Matrix) phủ `disabled` / `loading` / `error` / `busy` khi các argTypes đó tồn tại
+  - Mọi option enum `size` / `variant` rời rạc được mount trong story họ matrix
+  - `FullMatrix` khi ≥2 trong {size enums, variant enums, state keys} tồn tại — tích size × variant × key-state qua helper chung `stories/lib/matrix.jsx`
+- Toolbar globals: Theme × Element × Language (cùng trục với template). Element liệt kê **đủ 15** pack Ngũ Hành (Identity Lab / `tokens.elements` / EL map template) — không phải tập con.
+- **Docs/** hướng dẫn MDX công khai; **Release Notes/** prose sản phẩm curated (**không CHANGELOG.md**); **Status/** nhúng `_audit/run.html` full-bleed
+- Story **Maintainer/** cho bề mặt HTML portable (Motion, Identity Lab, templates, kitchen-sink, AI cluster, RTL; Atomic View chôn cho gates)
+- Cùng `styles.css` như production
+- Addon: `@storybook/addon-docs` + `@storybook/addon-a11y` (essentials gộp vào core ở SB10)
+
+## Config
+
+- `.storybook/main.js` — config Storybook 10 ESM, Vite + alias `@cs` → `components/`, **`base: '/'`** cho asset tại domain root
+- `.storybook/manager-head.html` — meta OG / canonical cho bề mặt production `/`
+- Autodocs qua `tags: ['autodocs']` trên CSF meta (không `docs.autodocs` trong main)
+
+## Consumer vẫn dùng (không đổi)
+
+| Audience | Consume |
+|---|---|
+| Static / bất kỳ framework | `styles.css` + `.cs-*` |
+| React production | `styles.css` + `_ds_bundle.js` |
+| ESM | `_esm/cs.mjs` |
+| Tokens | `tokens/*` |
+| Claude Design | `templates/**/*.dc.html` |
+
+## Lệnh
+
+```bash
+npm install
+npm run storybook
+npm run build:storybook    # → storybook-static/ (base `/`)
+npm run build:site         # đóng gói Storybook tại root .vercel-static/
+npm run test:storybook-contract
+```
+
+## Bản đồ
+
+Bề mặt HTML portable iframe từ Maintainer/* được liệt kê trong `docs/live-hub.md`. Status nhúng `_audit/run.html` (auto-run lần đầu; **Re-run** khi cần).

package/docs/vi/sync.md

@@ -0,0 +1,48 @@
+# 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 có khôi phục nguyên hệ thống không?
+
+**Trong session Claude Design — có.** Mọi thứ định nghĩa hệ thống là file text/asset thuần và round-trip lossless:
+- `styles.css` + `tokens/` + `base/` (mọi CSS + `tokens.json`/`tokens.js`)
+- `components/**` (`.jsx` + `.d.ts` + `.prompt.md` + `*.card.html`)
+- `templates/**/*.dc.html` (+ `ds-base.js`, `support.js`)
+- `guidelines/`, `ui_kits/`, `fonts/` (woff2), `assets/`, `docs/`, `_audit/*.html`
+
+- **`_esm/cs.mjs`** — entry ESM. Tiền tố underscore **không** nghĩa là build artifact hay gitignored ở đây (chỉ `uploads/`, `scraps/`, `_audit/exports/` là — xem Hygiene bên dưới); `_esm/` là source, cùng tầng với `templates/` hoặc `docs/`. Một lần port trước đã bỏ nó đúng vì giả định đó và làm gãy ESM smoke gate — nếu bạn port/copy cây này bằng tay, **explicit include mọi thư mục top-level danh sách này đặt tên**, đừng suy từ tiền tố `_`.
+
+- `README.md`, `CONTRIBUTING.md`, `SKILL.md`, `CLAUDE.md`, `VERSION`, `DESIGN.md` (open-spec surface generate — commit, chỉ regen qua `npm run build:design-md`, khóa bởi gate `design-md-parity`)
+
+Kéo chúng vào project mới (xem bên dưới) và compiler nhận lại như design system — nó khóa vào `styles.css`, cặp `.d.ts`/`.jsx`, HTML `@dsCard`, và `templates/`. File **derived** (`_ds_bundle.js`, `_ds_manifest.json`, `_adherence.oxlintrc.json`) được regenerate mỗi turn từ source, nên không cần tin từ repo — chúng rebuild.
+
+**Ở agent khác (Google Stitch, LLM tool generic) — một phần.** Chúng tiêu thụ được lớp **portable** — `tokens/tokens.json` + `tokens.js`, raw CSS, component `.jsx`, fonts, và Markdown docs — nhưng **không** hiểu format Design-Component `.dc.html` hay compiler điều khiển nó. Vậy agent non-Claude-Design nhận tokens, styles, và source component như file, không phải hành vi DC/tweak/compile live. Hướng những tool đó vào root **`DESIGN.md`** trước (open-spec kiểu Stitch generate: doctrine + mọi giá trị token + inventory, regen từ DTCG qua `npm run build:design-md` và khóa bởi gate `design-md-parity`), rồi `tokens.json` / `tokens.dtcg.json` và CSS cho hợp đồng máy; coi `.dc.html` + compiler là native Claude Design.
+
+## Đồng bộ hai chiều (repo = nguồn chân lý)
+
+Claude Design có thể **đọc/copy từ** GitHub nhưng **không push tới** nó. Vậy sync là *pull tự động, push thủ công*:
+**Bắt đầu session — pull (tin cậy, tự động):** bảo agent load repo. Nó copy cây vào project mới (đường `github_copy_files`), compiler validate, và bạn tiếp từ chân lý đã commit — không bao giờ từ project state cũ. Luôn bắt đầu đây; đừng resume từ project nửa nhớ.
+
+**Kết thúc session — push (thủ công, review):** tải project, rồi từ clone:
+```
+git checkout -b session/<date-or-topic>
+
+# copy file đã tải lên working tree (giữ .git/, .github/, LICENSE)
+git add -A && git commit -m "DS <VERSION> — <summary>"
+git push -u origin session/<date-or-topic>   # branch, không bao giờ --force, không bao giờ thẳng main
+
+# mở PR, review diff, merge
+```
+Diff PR là lưới an toàn — nó hiện đúng những gì đổi kể từ chân lý commit lần trước.
+
+## 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` cố định 1.0.0** — không bump và 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.
+
+- **Commit nhỏ, thường xuyên** hơn một dump khổng lồ cuối project — diff nhỏ an toàn hơn để review và ít khả năng lặng lẽ bỏ file.
+
+## TL;DR
+Push project này → repo là archive trung thành, khôi phục được **cho Claude Design** (pull lúc bắt đầu, compiler rebuild file derived). Agent khác nhận lớp token/style/JSX portable, không runtime DC. Làm hai chiều bằng **pull từ repo đầu mọi session và commit lại qua PR cuối** — repo giữ nguồn chân lý và không mất việc giữa session tạm.

package/docs/vi/template-schema-v2.md

@@ -0,0 +1,36 @@
+# Template content-schema v2 — content slot có kiểu
+
+Metadata thuần additive, opt-in: sidecar `templates/<slug>/content-schema.json` cạnh `.dc.html` của template, khai báo **kiểu** của mỗi `{{ hole }}` đã có trong template — để agent hoặc pipeline điền/validate nội dung khách thật theo chương trình mà không parse HTML hay đoán.
+
+**Không cần đổi markup template.** `id` của slot là tên hole đã dùng trong `.dc.html` (ví dụ `{{ heroH }}`) và đã bind trong `renderVals()` của logic class — schema chỉ mô tả nó.
+
+## Hình dạng
+
+```json
+{
+  "$schemaVersion": "2.0",
+  "template": "marketing-page",
+  "slots": [
+    { "id": "heroH", "type": "text", "label": "Hero headline", "maxLength": 70, "required": true },
+    { "id": "heroP", "type": "richtext", "label": "Hero paragraph" },
+    { "id": "svcKicker", "type": "text", "label": "Services eyebrow", "maxLength": 40 }
+  ]
+}
+```
+
+| Trường | Bắt buộc | Ghi chú |
+|---|---|---|
+| `$schemaVersion` | có | `"2.0"` cho spec này |
+| `template` | có | khớp tên thư mục `templates/<slug>/` |
+| `slots[].id` | có | phải bằng một hole `{{ id }}` thật trong `.dc.html` sibling |
+| `slots[].type` | có | một trong: `text`, `richtext`, `image`, `link`, `list`, `table`, `date` |
+| `slots[].label` | có | đọc được bởi người, cho UI điền nội dung |
+| `slots[].maxLength` | không | chỉ text/richtext — hướng dẫn soft, DC không enforce |
+| `slots[].required` | không | mặc định `false` |
+| `slots[].i18n` | không | `{"en": "...", "vi": "..."}` — cho template ship biến thể EN·VI |
+
+Hình dạng máy kiểm được chính thức nằm ở `templates/schema/content-schema.schema.json` (JSON Schema draft-07). `_audit/template-schema-test.html` validate mọi sidecar tồn tại — hai chiều: mọi slot id khai báo phải resolve tới hole thật trong template, và (informational) báo coverage trên toàn `templates/`.
+
+## Rollout
+
+Giống visual-diff baselines, ban đầu ship **cố ý chưa đầy đủ** — ba exemplar (một mỗi archetype lớn) chứng minh pattern end-to-end: `marketing-page` (product), `bod-report` (document), `slide-deck` (deck). Sau đó đã **quét tới mọi template hole-driven** và tiếp tục lớn dần; độ phủ sidecar hiện tại do `_audit/template-schema-test.html` báo cáo (bề mặt product traffic cao như `marketing-page`, `dashboard`, `settings`, cộng `tech-incident-report` được phủ slot nội dung đầy hơn). Hole trục / control-flow (`rootTheme`, `langAttr`, `elAttr`, `vaAttr`, `isEN`, `true`, …) nằm ngoài schema — chúng là trục runtime, không phải content author được. Phần còn lại hardcode copy bilingual trực tiếp theo nhánh `sc-if` ngôn ngữ (chưa có slot content `{{ hole }}`). Thêm sidecar cho mọi template nhận content hole-driven khi chạm tới; ưu tiên tăng measurable trên template traffic cao trước.

package/docs/viewer.html

@@ -0,0 +1,230 @@
+<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>CyberSkill · Docs</title>
+<link rel="stylesheet" href="../styles.css">
+<style>
+  *{box-sizing:border-box}html,body{height:100%}
+  body{margin:0;font-family:var(--cs-font-family-ui);background:var(--cs-color-surface-page);color:var(--cs-color-text-primary);display:grid;grid-template-columns:min(230px,36vw) 1fr}
+  aside{border-inline-end:1px solid var(--cs-color-border-default);background:var(--cs-color-surface-panel);overflow:auto;padding:14px 10px}
+  aside h1{font-size:13px;font-weight:800;margin:2px 8px 6px;color:var(--cs-color-brand-umber)}
+  [data-theme="dark"] aside h1{color:var(--cs-color-brand-ochre)}
+  .langtog{display:flex;gap:4px;margin:0 8px 10px}
+  .langtog button{flex:1;font:700 11px/1 var(--cs-font-family-ui);letter-spacing:.04em;padding:7px 0;border-radius:8px;border:1px solid var(--cs-color-border-default);background:var(--cs-color-surface-raised);color:var(--cs-color-text-muted);cursor:pointer}
+  .langtog button.on{background:var(--cs-color-brand-umber);color:var(--cs-color-text-inverse);border-color:var(--cs-color-brand-umber)}
+  [data-theme="dark"] .langtog button.on{background:var(--cs-color-brand-ochre);color:var(--cs-color-brand-umber);border-color:var(--cs-color-brand-ochre)}
+  .langhint{font-size:10.5px;color:var(--cs-color-text-muted);margin:0 10px 8px;line-height:1.4}
+  aside a{display:block;font-size:13px;font-weight:600;color:var(--cs-color-text-muted);text-decoration:none;padding:7px 10px;border-radius:8px}
+  aside a:hover{color:var(--cs-color-text-primary);background:var(--cs-color-surface-raised)}
+  aside a.on{color:var(--cs-color-brand-umber);background:var(--cs-color-surface-raised)}
+  [data-theme="dark"] aside a.on{color:var(--cs-color-brand-ochre)}
+  aside .grp{font-size:10.5px;font-weight:800;text-transform:uppercase;letter-spacing:.09em;color:var(--cs-color-text-muted);margin:14px 10px 5px}
+  #docsearch{box-sizing:border-box;border:1px solid var(--cs-color-border-default);border-radius:8px;background:var(--cs-color-surface-raised);padding:8px 10px;font:inherit;font-size:12.5px;margin:0 8px 10px;width:calc(100% - 16px)}
+  .searchres{font-size:12px;color:var(--cs-color-text-muted);padding:0 10px 6px}
+  .searchhit{display:block;padding:7px 10px;border-radius:8px;text-decoration:none;color:var(--cs-color-text-primary)}
+  .searchhit:hover{background:var(--cs-color-surface-raised)}
+  .searchhit b{color:var(--cs-color-brand-umber)}[data-theme="dark"] .searchhit b{color:var(--cs-color-brand-ochre)}
+  .searchhit .snip{display:block;font-size:11px;color:var(--cs-color-text-muted);font-weight:400;margin-top:2px}
+  mark{background:var(--cs-color-brand-ochre);color:var(--cs-color-brand-umber);border-radius:2px;padding:0 1px}
+  main{overflow:auto;padding:30px 38px}
+  article{max-width:820px;line-height:1.62;font-size:14.5px}
+  article h1{font-size:24px;letter-spacing:-.015em;margin:0 0 12px}
+  article h2{font-size:18px;margin:28px 0 8px;padding-top:10px;border-top:1px solid var(--cs-color-border-default)}
+  article h3{font-size:15px;margin:20px 0 6px}
+  article code{font-family:var(--cs-font-family-mono);font-size:.86em;background:var(--cs-color-surface-raised);border-radius:4px;padding:1px 5px}
+  article pre{background:var(--cs-color-surface-raised);border:1px solid var(--cs-color-border-default);border-radius:10px;padding:12px 14px;overflow:auto}
+  article pre code{background:none;padding:0;font-size:12px;line-height:1.55}
+  article table{border-collapse:collapse;margin:10px 0;width:100%}
+  article th,article td{border:1px solid var(--cs-color-border-default);padding:7px 10px;text-align:start;font-size:13px;vertical-align:top}
+  article th{background:var(--cs-color-surface-raised)}
+  article blockquote{margin:10px 0;padding:6px 14px;border-inline-start:3px solid var(--cs-color-brand-ochre);color:var(--cs-color-text-muted);background:var(--cs-color-surface-raised);border-radius:0 8px 8px 0}
+  article ul,article ol{padding-inline-start:22px}
+  article li{margin:3px 0;overflow-wrap:anywhere}
+  article p,article blockquote{overflow-wrap:anywhere}
+  article code{white-space:break-spaces;overflow-wrap:anywhere}
+  article hr{border:0;border-top:1px dashed var(--cs-color-border-default);margin:20px 0}
+  article a{color:var(--cs-color-link)}article a:hover{color:var(--cs-color-link-hover)}
+  #err{color:#B42318;font-family:var(--cs-font-family-mono);font-size:13px}
+  @media (max-width:640px){
+    body{grid-template-columns:1fr}
+    aside{border-inline-end:0;border-block-end:1px solid var(--cs-color-border-default);max-height:38vh}
+    main{padding:18px 16px}
+  }
+</style></head>
+<body>
+<aside id="nav"><h1>CyberSkill Docs</h1>
+<div class="langtog" role="group" aria-label="Doc language"><button type="button" id="lang-en" data-lang="en">EN</button><button type="button" id="lang-vi" data-lang="vi">VI</button></div>
+<p class="langhint" id="langhint">Operator docs under docs/ · entrance docs stay EN</p>
+<input id="docsearch" type="search" placeholder="Search all docs…"><div id="navlinks"></div></aside>
+<main><article id="doc"><p style="color:var(--cs-color-text-muted)">Loading…</p></article><p id="err" hidden></p></main>
+<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/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/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/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/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';
+function DOCS(){ return lang==='vi'?DOCS_VI:DOCS_EN; }
+const ALL=DOCS_EN.flatMap(g=>g[1].map(d=>d[0]));
+const nav=document.getElementById('navlinks');
+function syncLangUi(){
+  document.getElementById('lang-en').classList.toggle('on',lang==='en');
+  document.getElementById('lang-vi').classList.toggle('on',lang==='vi');
+  document.getElementById('langhint').textContent=lang==='vi'
+    ? 'docs/*.md → docs/vi/ · README/SKILL/llms/CONTRIBUTING vẫn EN'
+    : 'Operator docs under docs/ · entrance docs stay EN';
+  document.getElementById('docsearch').placeholder=lang==='vi'?'Tìm mọi docs…':'Search all docs…';
+  document.documentElement.lang=lang==='vi'?'vi':'en';
+}
+function renderNav(){ nav.innerHTML=''; for(const [g,items] of DOCS()){ const h=document.createElement('div'); h.className='grp'; h.textContent=g; nav.appendChild(h);
+  for(const [p,label] of items){ const a=document.createElement('a'); a.href='#'+p; a.dataset.p=p; a.textContent=label; nav.appendChild(a); } } }
+syncLangUi(); renderNav();
+document.querySelector('.langtog').addEventListener('click',(e)=>{
+  const b=e.target.closest('button[data-lang]'); if(!b) return;
+  lang=b.dataset.lang; localStorage.setItem('cs-docs-lang',lang);
+  syncLangUi(); renderNav(); markActive();
+  docCache=null; // refetch under new language
+  load(cur||'README.md');
+});
+function esc(s){ return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;'); }
+function labelsNow(){ const L={}; for(const [,items] of DOCS()) for(const [p,l] of items) L[p]=l; return L; }
+/** Logical nav path (docs/foo.md) → fetch path (docs/vi/foo.md when VI). Entrance docs stay EN. */
+function fetchPath(p){
+  if(lang==='vi' && p.startsWith('docs/') && !p.startsWith('docs/vi/')) return 'docs/vi/'+p.slice(5);
+  return p;
+}
+let docCache=null;
+async function ensureCache(){ if(docCache) return docCache; docCache={}; await Promise.all(ALL.map(async p=>{ try{ docCache[p]=await fetchDoc(fetchPath(p)); }catch(e){ docCache[p]=''; } })); return docCache; }
+function snippet(text,q){ const i=text.toLowerCase().indexOf(q.toLowerCase()); if(i<0) return ''; const s=Math.max(0,i-30), e=Math.min(text.length,i+q.length+50); return (s>0?'…':'')+esc(text.slice(s,e)).replace(new RegExp('('+q.replace(/[.*+?^${}()|[\]\\]/g,'\\$&')+')','ig'),'<mark>$1</mark>')+(e<text.length?'…':''); }
+function highlightIn(q){ if(!q) return; const doc=document.getElementById('doc'); const walker=document.createTreeWalker(doc,NodeFilter.SHOW_TEXT); const re=new RegExp(q.replace(/[.*+?^${}()|[\]\\]/g,'\\$&'),'i'); let node; while((node=walker.nextNode())){ if(re.test(node.nodeValue)){ const span=document.createElement('span'); const idx=node.nodeValue.search(re); const before=node.nodeValue.slice(0,idx), match=node.nodeValue.slice(idx,idx+q.length), after=node.nodeValue.slice(idx+q.length); span.innerHTML=esc(before)+'<mark>'+esc(match)+'</mark>'+esc(after); node.replaceWith(span); span.scrollIntoView({block:'center'}); break; } } }
+async function runSearch(q){
+  const cache=await ensureCache();
+  const LABEL=labelsNow();
+  const hits=ALL.filter(p=>cache[p] && cache[p].toLowerCase().includes(q.toLowerCase()));
+  nav.innerHTML='';
+  const res=document.createElement('div'); res.className='searchres'; res.textContent=hits.length+' match'+(hits.length===1?'':'es')+' for “'+q+'”'; nav.appendChild(res);
+  for(const p of hits){ const a=document.createElement('a'); a.className='searchhit'; a.href='#'+p;
+    a.innerHTML='<b>'+esc(LABEL[p]||p)+'</b><span class="snip">'+snippet(cache[p],q)+'</span>';
+    a.addEventListener('click',()=>{ setTimeout(()=>highlightIn(q),200); });
+    nav.appendChild(a); }
+}
+const searchBox=document.getElementById('docsearch');
+let searchT=null;
+searchBox.addEventListener('input',()=>{ clearTimeout(searchT); const q=searchBox.value.trim(); searchT=setTimeout(()=>{ if(q.length<2){ renderNav(); markActive(); } else { runSearch(q); } },150); });
+function markActive(){ document.querySelectorAll('#navlinks a').forEach(a=>a.classList.toggle('on',a.dataset.p===cur)); }
+function inline(s){ return esc(s)
+  .replace(/`([^`]+)`/g,(m,c)=>'<code>'+c+'</code>')
+  .replace(/\*\*([^*]+)\*\*/g,'<b>$1</b>')
+  .replace(/(^|[\s(])\*([^*\n]+)\*/g,'$1<i>$2</i>')
+  .replace(/\[([^\]]+)\]\(([^)\s]+)\)/g,'<a href="$2">$1</a>'); }
+function md(src){
+  src=src.replace(/\r/g,''); const fences=[];
+  src=src.replace(/```[\w-]*\n([\s\S]*?)```/g,(m,c)=>{ fences.push('<pre><code>'+esc(c)+'</code></pre>'); return '@@F'+(fences.length-1)+'@@'; });
+  const lines=src.split('\n'); const out=[]; let i=0;
+  const grab=(re)=>{ const acc=[]; while(i<lines.length&&re.test(lines[i])){ acc.push(lines[i]); i++; } return acc; };
+  while(i<lines.length){ const L=lines[i];
+    if(/^@@F\d+@@\s*$/.test(L)){ out.push(L.trim()); i++; continue; }
+    const h=/^(#{1,6})\s+(.*)$/.exec(L); if(h){ out.push('<h'+h[1].length+'>'+inline(h[2])+'</h'+h[1].length+'>'); i++; continue; }
+    if(/^\s*(-{3,}|\*{3,})\s*$/.test(L)){ out.push('<hr>'); i++; continue; }
+    if(/^\|/.test(L)){ const rows=grab(/^\|/); const cells=r=>r.replace(/^\||\|$/g,'').split('|').map(c=>inline(c.trim()));
+      let hd=null,body=rows; if(rows.length>1&&/^[\s|:\-]+$/.test(rows[1])){ hd=cells(rows[0]); body=rows.slice(2); }
+      out.push('<table>'+(hd?'<thead><tr>'+hd.map(c=>'<th>'+c+'</th>').join('')+'</tr></thead>':'')+'<tbody>'+body.map(r=>'<tr>'+cells(r).map(c=>'<td>'+c+'</td>').join('')+'</tr>').join('')+'</tbody></table>'); continue; }
+    if(/^\s*[-*+]\s+/.test(L)){
+      const li=[];
+      while(i<lines.length){
+        const t=lines[i];
+        const m=/^\s*[-*+]\s+(.*)$/.exec(t);
+        if(m){ li.push(m[1].trim()); i++; continue; }
+        // Soft-wrapped list continuation (no marker, not a new block)
+        if(li.length && t.trim() && !/^(#{1,6}\s|\||>\s?|```|\s*[-*+]\s|\s*\d+\.\s)/.test(t) && !/^\s*$/.test(t) && !/^@@F\d+@@/.test(t)){
+          li[li.length-1]+=' '+t.trim(); i++; continue;
+        }
+        break;
+      }
+      out.push('<ul>'+li.map(x=>'<li>'+inline(x)+'</li>').join('')+'</ul>');
+      continue;
+    }
+    if(/^\s*\d+\.\s+/.test(L)){
+      const li=[];
+      while(i<lines.length){
+        const t=lines[i];
+        const m=/^\s*\d+\.\s+(.*)$/.exec(t);
+        if(m){ li.push(m[1].trim()); i++; continue; }
+        if(li.length && t.trim() && !/^(#{1,6}\s|\||>\s?|```|\s*[-*+]\s|\s*\d+\.\s)/.test(t) && !/^\s*$/.test(t) && !/^@@F\d+@@/.test(t)){
+          li[li.length-1]+=' '+t.trim(); i++; continue;
+        }
+        break;
+      }
+      out.push('<ol>'+li.map(x=>'<li>'+inline(x)+'</li>').join('')+'</ol>');
+      continue;
+    }
+    if(/^>\s?/.test(L)){
+      // Soft-wrapped blockquote lines are one paragraph (join with space). Blank `>` lines split paragraphs.
+      const raw=grab(/^>\s?/).map(x=>x.replace(/^>\s?/,''));
+      const paras=[]; let cur=[];
+      for(const row of raw){
+        if(!row.trim()){ if(cur.length){ paras.push(cur.join(' ')); cur=[]; } continue; }
+        cur.push(row.trim());
+      }
+      if(cur.length) paras.push(cur.join(' '));
+      out.push('<blockquote>'+paras.map(p=>'<p style="margin:0 0 8px">'+inline(p)+'</p>').join('')+'</blockquote>');
+      continue;
+    }
+    if(/^\s*$/.test(L)){ i++; continue; }
+    const p=grab(/^(?!\s*$)(?!#{1,6}\s)(?!\|)(?!\s*[-*+]\s)(?!\s*\d+\.\s)(?!>)(?!@@F\d+@@\s*$)(?!\s*(-{3,}|\*{3,})\s*$)/);
+    // Soft-wrapped prose: join with a single space so mid-sentence hard wraps never render as breaks.
+    out.push('<p>'+p.map(l=>l.trim()).filter(Boolean).map(inline).join(' ')+'</p>');
+  }
+  return out.join('\n').replace(/@@F(\d+)@@/g,(m,n)=>fences[+n]);
+}
+function resolve(href,cur){ if(href.startsWith('./')) href=href.slice(2); const base=cur.includes('/')?cur.slice(0,cur.lastIndexOf('/')+1):''; let p=base+href; for(let k=0;k<6&&/(^|\/)\.\.\//.test(p);k++){ p=p.replace(/(^|\/)[^\/]+\/\.\.\//,'$1'); } return p.replace(/^\.\//,'').replace(/^\/+/,''); }
+let cur='';
+function docUrls(p){
+  // Prefer relative-to-viewer (../README.md when viewer is in docs/), then root-relative, then same-dir.
+  const base = new URL('.', location.href);
+  return [
+    new URL('../'+p, base).href,
+    new URL('/'+p, location.origin).href,
+    new URL(p, base).href,
+  ];
+}
+async function fetchDoc(p){
+  let lastErr;
+  for (const u of docUrls(p)){
+    try{
+      const r = await fetch(u, {cache:'no-cache'});
+      if(!r.ok){ lastErr = new Error(r.status+' '+r.statusText+' @ '+u); continue; }
+      const ct = (r.headers.get('content-type')||'').toLowerCase();
+      const text = await r.text();
+      if (ct.includes('text/html') && /<!DOCTYPE html|<html[\s>]/i.test(text.slice(0,200))) {
+        lastErr = new Error('hosting intercepted '+u+' (got HTML, not markdown)');
+        continue;
+      }
+      return text;
+    }catch(e){ lastErr = e; }
+  }
+  throw lastErr || new Error('all fetch paths failed');
+}
+async function load(p){
+  cur=p; document.title='CyberSkill · '+p+(lang==='vi' && p.startsWith('docs/')?' · VI':'');
+  markActive();
+  const doc=document.getElementById('doc'), err=document.getElementById('err');
+  err.hidden=true;
+  doc.innerHTML='<p style="color:var(--cs-color-text-muted)">Loading…</p>';
+  try{ doc.innerHTML=md(await fetchDoc(fetchPath(p))); document.querySelector('main').scrollTop=0; }
+  catch(e){ doc.innerHTML=''; err.hidden=false; err.textContent='Could not load '+fetchPath(p)+' — '+(e && e.message || e); }
+}
+document.getElementById('doc').addEventListener('click',(e)=>{
+  const a=e.target.closest('a'); if(!a) return; const href=a.getAttribute('href')||'';
+  if(/^(https?:|mailto:)/.test(href)){ a.target='_blank'; a.rel='noopener'; return; }
+  if(href.startsWith('#')) return;
+  e.preventDefault(); const p=resolve(href,cur);
+  if(ALL.includes(p)) location.hash=p; else window.open('../'+p,'_blank','noopener');
+});
+function route(){ const p=decodeURIComponent((location.hash||'').slice(1)); load(ALL.includes(p)?p:'README.md'); }
+window.addEventListener('hashchange',route); route();
+</script>
+</body></html>