@cyberskill/design 1.3.8 → 1.3.9

package/docs/quality-gates.md

@@ -1,10 +1,10 @@
 # Quality gates — the benchmark reference
 
-Every deterministic quality gate in the system, what it asserts, its pass criterion, whether it blocks (hard) or informs (advisory), and where it runs.
+Every deterministic quality gate in the system, what it asserts, its pass criterion, whether it blocks (hard) or informs (advisory), and where it runs. Published on Storybook **Docs** at `design.cyberskill.world`.
 
 **Where gates run.** *Fast board CI* = the `fast-gates` job in `.github/workflows/design-system-gates.yml`, which serves the repo and drives `_audit/run.html` headless via `_audit/ci/run-gates.mjs` (every push/PR + nightly + manual) — new board rows are picked up automatically. Two gates additionally run standalone as *merge blockers* (`docs-consistency-blocker` job, via `_audit/ci/run-single-gate.mjs`). *Whole-set CI* = the `whole-set-audits` job (every push/PR + nightly — owner decision B). *Unit test* = `npm run test:unit` in the `unit-tests` job (plain Node, no browser). *Node pre-checks* = the `node-prechecks` job (browser-free authorities: bundle freshness, DESIGN.md freshness, styles.min.css + contrast-report freshness, manifest coverage) plus the `token-provenance` job. *Storybook CI* = the `storybook-build` job (`build:storybook` + freshness `--require`). Every browser gate publishes a verdict global (`window.__*`) that the headless runners read.
 
-## Fast board — 40 gates in `_audit/run.html`
+## Fast board — 42 gates in `_audit/run.html`
 
 Benchmark principles (WCAG · APCA · OKLCH · DTCG · CDS doctrine + style expansion): [`docs/benchmark-rubric.md`](benchmark-rubric.md).
 
@@ -13,9 +13,11 @@ Benchmark principles (WCAG · APCA · OKLCH · DTCG · CDS doctrine + style expa
 | Contrast guard | `_audit/contrast-guard.html` | No base rule paints umber on a themeable surface without a dark override; every semantic text×surface pair scores in light and dark | 0 unshielded rules and 0 failing pairs (`__contrastguard`) | Hard | Fast board CI |
 | Axes guard | `_audit/axis-guard.html` | No live source reintroduces the retired Expression/Density product surface | 0 hits across manifest-indexed sources (`__axisguard`) | Hard | Fast board CI |
 | Manifest CSS paths | `_audit/manifest-css-guard.html` | Every `_ds_manifest.json` `globalCssPaths` entry exists as raw CSS; every `styles.css` `@import` is listed | 0 missing / 0 unlisted (`__cssguard`) | Hard | Fast board CI |
-| Docs consistency | `_audit/docs-consistency.html` | Every count claim in README/SKILL/llms.txt matches the compiler manifest; audit prose card-count claims (`_audit/index` / README / namespace-portability) match `manifest.cards`; `VERSION` is semver and `package.json` matches it (LAUNCHED 1.1.0; auto-bump on main); no changelog-file reference; stale-phrase blacklist (the retired suite/pack counts the Jul 2026 audit removed) clean across README/SKILL/llms + `docs/*.md` (historical notes under `_audit/archive/` are not scanned); `DESIGN.md` exists with front-matter version = `VERSION`; agent routing honesty — Claude path cites `_esm/cs.mjs` + bundle prefix; Stitch path forbids `*.dc.html` as SoT; package name `@cyberskill/design`; doctrine↔source parity — 10 accent roles incl. `on-strong`, full depth scale, default lang `vi` vs `i18n.js`, breakpoint CSS↔JSON, `base/` depth fallbacks vs `elevation.css` | 0 mismatched claims, 0 blacklist hits, VERSION sync + stamp + routing + doctrine parity intact (`__docs`) | Hard | Fast board CI + merge blocker |
+| Docs consistency | `_audit/docs-consistency.html` | Every count claim in README/SKILL/llms.txt matches the compiler manifest; audit prose card-count claims (`_audit/index` / README / namespace-portability) match `manifest.cards`; `VERSION` is semver and `package.json` matches it (LAUNCHED 1.1.0; auto-bump on main); no changelog-file reference; stale-phrase blacklist (the retired suite/pack counts the Jul 2026 audit removed) clean across README/SKILL/llms + `docs/*.md` (historical notes under `_audit/archive/` are not scanned); `DESIGN.md` exists with front-matter version = `VERSION`; agent routing honesty — SKILL/llms cite `_esm/cs.mjs` + bundle prefix; Stitch path forbids `*.dc.html` as SoT; package name `@cyberskill/design`; doctrine↔source parity — 10 accent roles incl. `on-strong`, full depth scale, default lang `vi` vs `i18n.js`, breakpoint CSS↔JSON, `base/` depth fallbacks vs `elevation.css` | 0 mismatched claims, 0 blacklist hits, VERSION sync + stamp + routing + doctrine parity intact (`__docs`) | Hard | Fast board CI + merge blocker |
 | Asset-weight budget | `_audit/asset-weight-budget.html` | Elemental aurora WebPs (`assets/aurora-{tho,hoa,thuy,moc,kim}.webp`) stay under regression ceilings (≤300 KB each, ≤1.2 MB set); legacy aurora PNGs fail; wash CSS must not point at the Thổ JPEG | All five present under ceilings (`__assetweight`) | Hard | Fast board CI (+ Node twin in `test-docs-consistency.mjs`) |
 | Docs language parity | `_audit/docs-lang-parity.html` | Every operator-facing EN `docs/*.md` has a `docs/vi/` counterpart; VI is not an empty/TODO stub (≥40% EN length); stale-phrase blacklist clean on both EN and VI (historical notes under `_audit/archive/` are not tracked) | 0 missing pairs, 0 stubs, 0 blacklist hits (`__docslangparity`) | Hard | Fast board CI |
+| Docs Storybook coverage | `_audit/docs-storybook-coverage.html` | Live HTML: published catalog + `/docs/**` + viewer + entrance files; Storybook `index.json` titles when present (never unpublished `.storybook/` / `stories/`). Node twin: CSF/MDX source + `staticDirs` | 0 missing published pages / viewer entries (`__docssbcoverage`) | Hard | Fast board CI + unit twin |
+| Docs link check | `_audit/docs-link-check.html` | Live HTML: published markdown + viewer links resolve; no retired paths. Node twin also scans unpublished MDX `href`/`src` | 0 broken in-repo links (`__docslinkcheck`) | Hard | Fast board CI + unit twin |
 | DESIGN.md parity | `_audit/design-md-parity.html` | The root `DESIGN.md` (Stitch open-spec surface) byte-equals an in-browser regeneration from `tokens.dtcg.json` + `_ds_manifest.json` + `VERSION` via the shared `scripts/design-md-lib.mjs`; every token row re-checked individually (the count is printed with the verdict) | Byte-identical + 0 drifted rows (`__designmd`) | Hard | Fast board CI |
 | Version stamp | `_audit/version-stamp.html` | `package.json`, `tokens.json`/`tokens.js` metas, DTCG `$extensions`, `provenance.json` release + dtcgStamp, `DESIGN.md` front matter, and `_esm/cs.mjs` `export const VERSION` all equal `VERSION` (pin tracks file; LAUNCHED at 1.1.0) | All 9 stamps equal (`__versionstamp`) | Hard | Fast board CI |
 | Namespace portability | `_audit/namespace-portability.html` | No manifest-indexed source hardcodes the compiler's project-id bundle suffix | 0 hardcoded suffixes (`__nsguard`) | Hard | Fast board CI |
@@ -78,6 +80,8 @@ Benchmark principles (WCAG · APCA · OKLCH · DTCG · CDS doctrine + style expa
 | Nav model | `_audit/ci/test-nav-model.mjs` | The shipped `guidelines/nav-model.js` classify/group logic behaves (drives the real module) | All assertions pass (exit 0) | Hard | Unit test |
 | Health/Tokens UI contract | `_audit/ci/test-health-tokens-contract.mjs` | Structural contracts of the Health + Tokens HTML entry points hold | All assertions pass (exit 0) | Hard | Unit test |
 | Docs consistency (Node twin) | `_audit/ci/test-docs-consistency.mjs` | Doctrine↔source parity (roles/depth/lang/breakpoints/fallbacks) + aurora asset-weight ceilings | All assertions pass (exit 0) | Hard | Unit test |
+| Docs Storybook coverage (Node twin) | `_audit/ci/test-docs-storybook-coverage.mjs` | Tracked docs + entrance + doctrine each have a Storybook story title and a viewer nav path; `staticDirs` includes `docs/` | Exit 0 | Hard | Unit test |
+| Docs link check (Node twin) | `_audit/ci/test-docs-link-check.mjs` | In-repo relative links in the required published set resolve; retired paths absent as live hrefs | Exit 0 | Hard | Unit test |
 | Form paths | `_audit/ci/test-form-paths.mjs` | Form path helpers behave (drives the shipped `Form.jsx` via dynamic import) | All assertions pass (exit 0) | Hard | Unit test |
 | Storybook contract | `_audit/ci/test-storybook-contract.mjs` | Live hub is Storybook only; SB10 ESM main + addon-docs/a11y; complete CSF for every public primary; Matrix/AllVariants + AllSizes when `argTypes.size`; States/Matrix cover disabled/loading/error/busy; every discrete size/variant enum mounted; FullMatrix required when ≥1 of {size, variant, state} axes exist (≥28 qualifiers) | All assertions pass (exit 0) | Hard | Unit test |
 | Axe coverage | `_audit/ci/test-axe-coverage.mjs` | Fixture `NAMES` ≡ `listPublicComponents()`; axe-smoke loads inventory-locked fixtures | All assertions pass (exit 0) | Hard | Unit test |

package/docs/release-notes.md

@@ -1,6 +1,6 @@
 # Release Notes
 
-Curated product highlights for operators. This is **not** a git log and **not** a `CHANGELOG.md` — the design system does not maintain a changelog file. Version is **LAUNCHED at 1.1.0**; **pin tracks `VERSION`** (auto-bump on push to `main` from Conventional Commits; owner may still force a bump). Technical continuity is the repo tip; product-facing continuity is this page (mirrored in Storybook **Release Notes**).
+Curated product highlights for operators. This is **not** a git log and **not** a `CHANGELOG.md` — the design system does not maintain a changelog file. Version is **LAUNCHED at 1.1.0**; **pin tracks `VERSION`** (auto-bump on push to `main` from Conventional Commits; owner may still force a bump). Technical continuity is the repo tip; product-facing continuity is this page (mirrored in Storybook **Release Notes**). Published on Storybook **Docs** at `design.cyberskill.world`.
 
 ## Patch — `@cyberskill/design@1.1.1`
 

package/docs/release-runbook.md

@@ -1,6 +1,6 @@
 # Release runbook (authoritative)
 
-One page for how a release happens and how to tell it worked. Consolidates areas 21/23. Related detail: `docs/ci-cd.md`, `docs/deploy.md`, `docs/decisions.md` §7 / §13.
+One page for how a release happens and how to tell it worked. Consolidates areas 21/23. Related detail: `docs/ci-cd.md`, `docs/deploy.md`, `docs/decisions.md` §7 / §13. Published on Storybook **Docs** at `design.cyberskill.world`.
 
 ## Trigger
 

package/docs/storybook.md

@@ -1,6 +1,6 @@
 # Storybook — product surface at `/` (host)
 
-Storybook **10** is the **product site** for operators on `design.cyberskill.world` (`/`). It is still **not** part of the portable consumer contract.
+Storybook **10** is the **product site** for operators on `design.cyberskill.world` (`/`). It is still **not** part of the portable consumer contract. Published on Storybook **Docs** at `design.cyberskill.world`.
 
 ## URL
 
@@ -20,7 +20,7 @@ Storybook **10** is the **product site** for operators on `design.cyberskill.wor
   - Every discrete `size` / `variant` enum option mounted in a matrix-family story
   - `FullMatrix` when ≥1 of {size enums, variant enums, state keys} exist — the size × variant × key-state product via shared helpers in `stories/lib/matrix.jsx`
 - Toolbar globals: Theme (light · dark · **system**) × Element × Language × Style (same axes as templates / Atomic View). Element lists **all 15** Ngũ Hành packs (`tokens.elements` / template EL maps / Storybook toolbar) — not a subset. Style’s sole pack is **liquid-glass**.
-- **Docs/** public MDX guides; **Release Notes/** curated product prose (**no CHANGELOG.md**); **Status/** embeds `_audit/run.html` full-bleed
+- **Docs/** published operator documentation — nested **Start / Guides / Maintainers**, curated MDX for high-traffic pages, one sidebar story per tracked markdown page, and a Documentation Library iframe of `/docs/viewer.html` (EN·VI). Canonical prose remains `docs/*.md`; Storybook is the live reading surface. **Release Notes/** curated product prose (**no CHANGELOG.md**); **Status/** embeds `_audit/run.html` full-bleed
 - **Maintainer/** stories for portable HTML surfaces (Motion, templates, kitchen-sink, AI cluster, RTL; Atomic View buried for gates)
 - Same `styles.css` as production
 - Addons: `@storybook/addon-docs` + `@storybook/addon-a11y` (essentials folded into core in SB10)
@@ -40,7 +40,7 @@ Storybook **10** is the **product site** for operators on `design.cyberskill.wor
 | ESM (bundler) | `_esm/react.mjs` (default / `@cyberskill/design/react`) |
 | ESM (browser legacy) | `_esm/cs.mjs` (`@cyberskill/design/legacy`) |
 | Tokens | `tokens/*` |
-| Claude Design | `templates/**/*.dc.html` |
+| DC-capable authoring | `templates/**/*.dc.html` |
 
 ## Commands
 

package/docs/sync.md

@@ -1,10 +1,10 @@
-# Repo ↔ Claude Design — round-trip fidelity & two-way sync
+# Repo ↔ authoring environment — round-trip fidelity & two-way sync
 
-The GitHub repo (`cyberskill-official/design`) is the **source of truth**. Claude Design sessions are ephemeral project filesystems — this doc is how they stay in sync without losing work.
+The GitHub repo (`cyberskill-official/design`) is the **source of truth**. Compiler sessions (for example Claude Design) are ephemeral project filesystems — this doc is how they stay in sync without losing work. Published on Storybook **Docs** at `design.cyberskill.world`.
 
 ## Does the repo restore the full system intact?
 
-**In a Claude-Design session — yes.** Everything that defines the system is plain text/asset files and round-trips losslessly:
+**In a DC-capable compiler session — yes.** Everything that defines the system is plain text/asset files and round-trips losslessly:
 - `styles.css` + `tokens/` + `base/` (all CSS + `tokens.json`/`tokens.js`)
 - `components/**` (`.jsx` + `.d.ts` + `.prompt.md` + `*.card.html`)
 - `templates/**/*.dc.html` (+ `ds-base.js`, `support.js`)
@@ -13,15 +13,15 @@ The GitHub repo (`cyberskill-official/design`) is the **source of truth**. Claud
 - **`_esm/react.mjs`** — bundler-native React entry (default package export; React peer). Regenerated via `npm run build:react-entry`.
 - **`_esm/cs.mjs`** — the browser / no-build legacy ESM entry (`@cyberskill/design/legacy`). Underscore-prefixed does **not** mean build artifact or gitignored here (only `uploads/`, `scraps/`, `_audit/exports/` are — see Hygiene below); `_esm/` is source, same tier as `templates/` or `docs/`. A prior port of this repo skipped it on exactly this assumption and broke the ESM smoke gate — if you're porting/copying this tree by hand, **explicitly include every top-level folder this list names**, don't infer from the `_` prefix.
 
-- `README.md`, `CONTRIBUTING.md`, `SKILL.md`, `CLAUDE.md`, `VERSION`, `DESIGN.md` (generated open-spec surface — committed, regenerated only via `npm run build:design-md`, pinned by the `design-md-parity` gate)
+- `README.md`, `CONTRIBUTING.md`, `SKILL.md`, `docs/doctrine.md`, host shims (`CLAUDE.md`), `VERSION`, `DESIGN.md` (generated open-spec surface — committed, regenerated only via `npm run build:design-md`, pinned by the `design-md-parity` gate)
 
-Pull them back into a fresh project (see below) and the compiler re-recognizes it as a design system — it keys off `styles.css`, the `.d.ts`/`.jsx` pairs, `@dsCard` HTML, and `templates/`. The **derived** files (`_ds_bundle.js`, `_ds_manifest.json`, `_adherence.oxlintrc.json`) are regenerated every turn from source, so they need not be trusted from the repo — they rebuild.
+Pull them back into a fresh project (see below) and the compiler re-recognizes it as a design system — it keys off `styles.css`, the `.d.ts`/`.jsx` pairs, `@dsCard` HTML, and `templates/`. Committed compiled artifacts (`_ds_bundle.js`, `_ds_manifest.json`, `_adherence.oxlintrc.json`, `dist/styles.min.css`, `DESIGN.md`) are part of the consumer contract — keep them in the tree and regenerate them with the documented npm scripts rather than treating them as disposable.
 
-**In other agents (Google Stitch, generic LLM tools) — partially.** They can consume the **portable** layer — `tokens/tokens.json` + `tokens.js`, the raw CSS, the component `.jsx`, fonts, and the Markdown docs — but they do **not** understand the `.dc.html` Design-Component format or the compiler that drives it. So a non-Claude-Design agent gets the tokens, styles, and component source as files, not the live DC/tweak/compile behavior. Point those tools at the root **`DESIGN.md`** first (the generated Stitch-style open-spec surface: doctrine + every token value + inventory, regenerated from DTCG via `npm run build:design-md` and pinned by the `design-md-parity` gate), then `tokens.json` / `tokens.dtcg.json` and the CSS for the machine contract; treat `.dc.html` + the compiler as Claude-Design-native.
+**In other agents (Google Stitch, generic LLM tools) — partially.** They can consume the **portable** layer — `tokens/tokens.json` + `tokens.js`, the raw CSS, the component `.jsx`, fonts, and the Markdown docs — but they do **not** understand the `.dc.html` Design-Component format or the compiler that drives it. So a non-compiler agent gets the tokens, styles, and component source as files, not the live DC/tweak/compile behavior. Point those tools at the root **`DESIGN.md`** first (the generated Stitch-style open-spec surface: doctrine + every token value + inventory, regenerated from DTCG via `npm run build:design-md` and pinned by the `design-md-parity` gate), then `tokens.json` / `tokens.dtcg.json` and the CSS for the machine contract; treat `.dc.html` + the compiler as DC-native.
 
 ## Two-way sync (repo = source of truth)
 
-Claude Design can **read/copy from** GitHub but **cannot push to** it. So sync is *automatic pull, manual push*:
+Compiler sessions can **read/copy from** GitHub but typically **cannot push to** it. So sync is *automatic pull, manual push*:
 **Session START — pull (reliable, automated):** tell the agent to load the repo. It copies the tree into the fresh project (the `github_copy_files` path), the compiler validates, and you continue from the committed truth — never from stale project state. Always begin here; do not resume from a half-remembered project.
 
 **Session END — push (manual, reviewed):** download the project, then from a clone:
@@ -37,7 +37,7 @@ git push -u origin session/<date-or-topic>   # branch, never --force, never stra
 The PR diff is the safety net — it shows exactly what changed since the last committed truth.
 
 ## Hygiene that keeps round-trips clean
-- **`.gitignore`** the transient (`uploads/`, `scraps/`, `_audit/exports/`); commit everything else, **including `_esm/`** (see above — it is source, not a build artifact, despite the `_` prefix). The compiled `_ds_bundle.js`/manifest are committed for consumers that have no build step, but expect churn — or ignore them and let each session regenerate.
+- **`.gitignore`** the transient (`uploads/`, `scraps/`, `_audit/exports/`); commit everything else, **including `_esm/`** (see above — it is source, not a build artifact, despite the `_` prefix). The compiled `_ds_bundle.js`, `_ds_manifest.json`, and `_adherence.oxlintrc.json` are **committed consumer artifacts** — they ship in the npm package so consumers with no build step can load the system. Do not gitignore them. Regenerate via `npm run build:bundle` after source changes; the bundle-freshness gate fails on drift.
 
 - **`VERSION` is LAUNCHED at 1.1.0; pin tracks `VERSION`** — auto-bump on push to `main` (`.github/workflows/version.yml` → tag `v*` → `npm-publish.yml`); owner may still force a bump. Do not maintain a changelog file. Continuity is the git history; open maintainer tasks live in `docs/decisions.md`.
 

package/docs/template-schema-v2.md

@@ -1,6 +1,6 @@
 # Template content-schema v2 — typed content slots
 
-Purely additive, opt-in metadata: a sidecar `templates/<slug>/content-schema.json` next to a template's `.dc.html`, declaring the **type** of each `{{ hole }}` already in the template — so an agent or pipeline can populate/validate real client content programmatically without parsing HTML or guessing.
+Purely additive, opt-in metadata: a sidecar `templates/<slug>/content-schema.json` next to a template's `.dc.html`, declaring the **type** of each `{{ hole }}` already in the template — so an agent or pipeline can populate/validate real client content programmatically without parsing HTML or guessing. Published on Storybook **Docs** at `design.cyberskill.world`.
 
 **Zero template-markup changes required.** The slot `id` is the hole name already used in the `.dc.html` (e.g. `{{ heroH }}`) and already bound in the logic class's `renderVals()` — the schema just describes it.
 

package/docs/vi/benchmark-rubric.md

@@ -1,6 +1,6 @@
 # Rubric benchmark Design System
 
-Checklist tự kiểm khi tiến hóa CyberSkill Design System — chuẩn bên ngoài cộng rule CDS. Ghép với [`docs/vi/quality-gates.md`](quality-gates.md) (gate xác định) và [`docs/vi/design-styles.md`](design-styles.md) (hợp đồng màu Element).
+Checklist tự kiểm khi tiến hóa CyberSkill Design System — chuẩn bên ngoài cộng rule CDS. Ghép với [`docs/vi/quality-gates.md`](quality-gates.md) (gate xác định) và [`docs/vi/design-styles.md`](design-styles.md) (hợp đồng màu Element). Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 ## Chuẩn bên ngoài
 
@@ -22,7 +22,7 @@ Checklist tự kiểm khi tiến hóa CyberSkill Design System — chuẩn bên
 | Chữ không trên mid `-accent`; focus Ochre không remap; màu status không remap | Hợp đồng `elements.css` · contrast-report · conventions |
 | Một element mỗi bề mặt; gradient chỉ Tương sinh | Registry products · conventions |
 | Registry product→element khóa; UI kit trung thành Thổ | [`docs/vi/products.md`](products.md) |
-| Expansion Rule đủ + `_audit/run.html` xanh + docs EN·VI parity | CLAUDE.md · docs-consistency · docs-lang-parity |
+| Expansion Rule đủ + `_audit/run.html` xanh + docs EN·VI parity | `docs/doctrine.md` · docs-consistency · docs-lang-parity · docs-storybook-coverage |
 | VERSION theo file (LAUNCH 1.1.0; auto-bump trên main) | version-stamp · docs-consistency |
 | Pack Element chỉ từ seed (30 bộ) | `element-geometry` · `tokens:elements` |
 

package/docs/vi/ci-cd.md

@@ -1,6 +1,6 @@
 # CI/CD — tự động hóa bảng gate
 
-**Gate CI** (workflow này) vẫn coi design system như cây tĩnh: serve repo, mở `_audit/run.html` headless, đọc verdict globals. Không cần product bundler cho gates.
+**Gate CI** (workflow này) vẫn coi design system như cây tĩnh: serve repo, mở `_audit/run.html` headless, đọc verdict globals. Không cần product bundler cho gates. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 **Host deploy** (Vercel, tách khỏi workflow này) chạy `npm install` + `npm run build:site` để Storybook ship làm bề mặt sản phẩm tại `/` — xem `docs/deploy.md` và `docs/storybook.md`. Đường đóng gói host đó không bắt buộc cho consuming project hay các job gate bên dưới.
 

package/docs/vi/consumer-grant.md

@@ -1,6 +1,6 @@
 # Grant consumer — `@cyberskill/design`
 
-**Trạng thái: có hiệu lực** (Th7 2026). Văn bản chính sách — không phải secret. License trên package vẫn **UNLICENSED**; grant này là lớp duyệt dùng trong các sản phẩm đã nêu.
+**Trạng thái: có hiệu lực** (Th7 2026). Văn bản chính sách — không phải secret. License trên package vẫn **UNLICENSED**; grant này là lớp duyệt dùng trong các sản phẩm đã nêu. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 ## Grant
 

package/docs/vi/consuming.md

@@ -1,10 +1,14 @@
 # Tiêu thụ & nâng cấp CyberSkill Design System
 
-Cách mọi project — do người hoặc agent điều khiển — áp dụng design system HTML-first này, và cách nhận update an toàn.
+Cách mọi project — do người hoặc agent điều khiển — áp dụng design system HTML-first này, và cách nhận update an toàn. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 **Tên package:** `@cyberskill/design` (xem `package.json`). Không coi `@cyberskill/react` lịch sử là đường cài cho monolith này.
 
-## Claude Code vs Google Stitch
+## Khi nào dùng
+
+Bạn đang cài, liên kết, hoặc nâng cấp hệ thống trong sản phẩm khác. Maintainer mở rộng hệ thống bắt đầu từ `docs/doctrine.md`.
+
+## Capability paths (DC-capable vs static)
 
 | Consumer | Bắt đầu tại | Hoạt động hôm nay | Không làm |
 |---|---|---|---|
@@ -17,11 +21,11 @@ Cách mọi project — do người hoặc agent điều khiển — áp dụng
 
 **Tín hiệu release:** đã LAUNCH ở **1.1.0**; **pin theo `VERSION`** (không CHANGELOG). Coi **git tip SHA** là chân lý kỹ thuật; đọc điểm nổi bật sản phẩm curated trong `docs/release-notes.md`.
 
-## Đường nhanh cho AI agent (Claude Code, hoặc điều khiển một agent)
+## Đường nhanh cho AI agent (DC-capable authoring, hoặc điều khiển một agent)
 
 **Bạn nhận:** `styles.css` (400+ token + class `.cs-*` + bề mặt Liquid Glass, `@import` `tokens/` + `base/`) · `_ds_bundle.js` (React component đã compile, không cần build) · `_esm/react.mjs` (entry React bundler-native — React là peerDependency; mặc định `exports["."]`) · `_esm/cs.mjs` (browser / no-build legacy qua `exports["./legacy"]`) · `_ds_manifest.json` (inventory máy đọc được) · mỗi component `Name.d.ts` (API) + `Name.prompt.md` (brief dùng) · `tokens/tokens.dtcg.json` (W3C DTCG) + `tokens.json`/`tokens.js`.
 
-**Checkout repo** — clone hoặc copy cả cây; mọi thứ là static đường dẫn tương đối. Điểm vào: Storybook trên host site (`/` / `npm run storybook`) · `guidelines/atomic-view.html` (mọi component live, portable) · `templates/<slug>/` (điểm bắt đầu copy được — DC cho Claude Design; kitchen-sink / `.cs-*` cho Stitch). Đọc `SKILL.md` trước khi author bất kỳ thứ gì on-brand; reader Stitch bắt đầu tại `DESIGN.md`. Bản đồ sâu hơn ở `llms.txt` (inventory) và file này (hướng dẫn adopt + upgrade đầy đủ bên dưới).
+**Checkout repo** — clone hoặc copy cả cây; mọi thứ là static đường dẫn tương đối. Điểm vào: Storybook trên host site (`/` / `npm run storybook`) · `guidelines/atomic-view.html` (mọi component live, portable) · `templates/<slug>/` (điểm bắt đầu copy được — DC khi có compiler; kitchen-sink / `.cs-*` cho Stitch / static). Đọc `SKILL.md` trước khi author bất kỳ thứ gì on-brand; reader Stitch bắt đầu tại `DESIGN.md`. Bản đồ sâu hơn ở `llms.txt` (inventory) và file này (hướng dẫn adopt + upgrade đầy đủ bên dưới).
 
 **Sau import — chứng minh health.** Mở `_audit/run.html`, để bảng gate chạy xong (mọi fast gate). Tất cả xanh = bản copy nhất quán nội bộ (contrast, docs, portability, tokens, consumer path, behavior, a11y, stories, bilingual parity). Chỉ full-clone — `_audit/` không nằm trong tarball npm.
 
@@ -34,7 +38,7 @@ Cách mọi project — do người hoặc agent điều khiển — áp dụng
 
 - Anchors (Umber/Ochre), tên class `.cs-*`, tên token `--cs-*` là hợp đồng ổn định.
 
-- Mở rộng hệ thống? Theo `CONTRIBUTING.md` (Expansion Rule: lan tới mọi deliverable trong một change; verify qua `_audit/`).
+- Mở rộng hệ thống? Theo `docs/doctrine.md` và `CONTRIBUTING.md` (Expansion Rule: lan tới mọi deliverable trong một change; verify qua `_audit/`).
 
 ## Adopt qua npm (tùy chọn)
 

package/docs/vi/contrast-report.md

@@ -1,6 +1,8 @@
 # Báo cáo contrast — cặp elemental (APCA)
 
-Tạo · quét tại VERSION 1.3.8.
+Tạo · quét tại VERSION 1.3.9.
+
+Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 **Doctrine của sweep này:** chữ ngồi trên `-bright` hoặc `-tint`, không bao giờ trên mid-tone `-accent`. Accent chỉ cho bar, border, progress, fill không chữ. (Rule trong `tokens/elements.css` và conventions.)
 

package/docs/vi/conventions.md

@@ -1,6 +1,6 @@
 # Conventions — authoring CyberSkill DS
 
-Cho người và agent *mở rộng hệ thống này*. (Consumer: đọc `SKILL.md`.) Compiler là nguồn chân lý cho đếm; prose mô tả hình dạng, không bao giờ số.
+Cho người và agent *mở rộng hệ thống này*. (Consumer: đọc `SKILL.md`.) Học thuyết mở rộng và kiểm chứng: `docs/doctrine.md`. Compiler là nguồn chân lý cho đếm; prose mô tả hình dạng, không bao giờ số. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 ## Quy tắc expansion
 

package/docs/vi/decisions.md

@@ -1,6 +1,6 @@
 # Quyết định (maintainer)
 
-Các lựa chọn của owner định hình CI, đồng bộ Figma, và phân phối. How-to nằm ở `docs/figma.md` và `docs/ci-cd.md` — file này chỉ là biên bản quyết định. Không phải hướng dẫn consumer.
+Các lựa chọn của owner định hình CI, đồng bộ Figma, và phân phối. How-to nằm ở `docs/figma.md` và `docs/ci-cd.md` — file này chỉ là biên bản quyết định. Không phải hướng dẫn consumer. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 ## 1. Whole-set audits trên mọi PR
 

package/docs/vi/deploy.md

@@ -1,5 +1,7 @@
 # Deploy site Atomic live (Vercel / VPS / mọi static host)
 
+Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
+
 Hai track:
 
 1. **Design system portable (consumers)** — vẫn là cây file tĩnh: không cần bundler. Link `styles.css` + tùy chọn `_ds_bundle.js` / ESM. Claude Design, Google Stitch, và product app không cần Node hay Storybook.
@@ -67,7 +69,7 @@ server {
 ```
 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`.
+**Netlify / Cloudflare Pages / tương tự:** file `_headers` ở root 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ũ).

package/docs/vi/design-styles.md

@@ -1,6 +1,6 @@
 # Phong cách thiết kế
 
-Các trục styling sống là **Theme × Element × Language × Style**. Pack Style duy nhất hôm nay là **liquid-glass** (vắng `data-cs-style` ≡ liquid-glass — cùng pattern mặc định với light theme / Thổ middle).
+Các trục styling sống là **Theme × Element × Language × Style**. Pack Style duy nhất hôm nay là **liquid-glass** (vắng `data-cs-style` ≡ liquid-glass — cùng pattern mặc định với light theme / Thổ middle). Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 | Trục | Cách đặt | Thay đổi gì |
 |---|---|---|

package/docs/vi/doctrine.md

@@ -0,0 +1,51 @@
+# Học thuyết
+
+Quy tắc chuẩn cho việc mở rộng và kiểm chứng Hệ thống Thiết kế CyberSkill. File theo từng host (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`) chỉ là shim trỏ về đây. Người tiêu thụ bắt đầu từ `SKILL.md` và thanh bên **Docs** trên Storybook tại `design.cyberskill.world`. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
+
+## Khi nào dùng
+
+- Bạn đang thêm hoặc đổi element, variant, icon, component, vai trò token, ngôn ngữ, hoặc mẫu template.
+- Bạn đang kiểm chứng một thay đổi trước khi tuyên bố xong.
+- Bạn cần các bất biến không được thiết kế lại tùy tiện.
+
+## Ngoài phạm vi
+
+File này không phải changelog, không phải sổ đăng ký sản phẩm, và không phải hướng dẫn tiêu thụ. Ánh xạ sản phẩm → element nằm ở `docs/products.md`. Đường dẫn adoption nằm ở `docs/consuming.md`.
+
+## Quy tắc mở rộng
+
+Khi **bất kỳ thứ gì** trong hệ thống này lớn lên, cập nhật **mọi deliverable trong cùng một thay đổi**:
+
+1. Token và nguồn (`tokens/`, component `.jsx` + `.d.ts` + `.prompt.md`).
+2. Thẻ mẫu (guidelines cộng thẻ nhóm component) **và mọi trang guideline liên quan**.
+3. **Tất cả** template (enum tweak, bản đồ EL/EX, accent đã quét).
+4. UI kit — trang kit trung thành Thổ; demo trục qua thanh công cụ Storybook và Atomic View (Identity Lab đã nghỉ).
+5. Docs: README (số đếm theo compiler), `SKILL.md`, file này, `docs/conventions.md`, **và mọi tài liệu liên quan mà thay đổi chạm tới** (README kit, `docs/products.md`, tái sinh `docs/contrast-report.md` sau khi đổi token). Xuất bản cùng các trang đó qua Storybook Docs (xem `docs/storybook.md`). **`VERSION` tự tăng khi đẩy lên `main`** từ Conventional Commits (`.github/workflows/version.yml` → tag `v*` → `npm-publish.yml`); chủ sở hữu vẫn có thể ép bump qua `Release-As:` / `workflow_dispatch`. **Không duy trì file changelog** — LAUNCHED tại **1.1.0**; pin theo `VERSION`. Tính liên tục là lịch sử git cộng Release Notes đã chọn lọc.
+6. Bề mặt duyệt và sức khỏe: component mới hoặc đổi được một story Atomic View trong `guidelines/atomic-view.html` (cộng playground sống nếu có prop chỉnh được — `_audit/story-coverage.html` bắt story) và phủ hành vi trong `_audit/component-behavior-test.html` nếu tương tác; mọi trục, công cụ, hoặc tab mới được nối vào `_audit/index.html` và Storybook **Status** (`_audit/run.html` full-bleed — `dashboard.html` chỉ redirect); gate xác định tương ứng được thêm hoặc cập nhật (`contrast-guard` cho quy tắc màu mới, `token-contract` cộng ma trận contrast cho token, `story-coverage` cho component, `docs-storybook-coverage` cho docs đã xuất bản).
+
+**Gate:** `check_design_system` sạch (chỉ phiên compiler) **cộng** `_audit/run.html` (mọi gate nhanh) xanh **cộng** `docs-consistency` xanh **cộng** grep enum hoặc danh sách cũ để chứng minh không bỏ sót. Trên clone portable, tương đương là bảng nhanh cộng `npm run test:unit`.
+
+Ranh giới phạm vi đã ghi (học thuyết, không phải lỗ hổng): trang UI-kit vẫn tái tạo trung thành Thổ; song ngữ EN·VN phủ email cộng tài liệu team, pháp lý, và tài chính (tài sản khách/truyền thông ưu tiên EN); chữ không bao giờ nằm trên `-accent` tông giữa.
+
+## Độ sâu kiểm chứng
+
+Kiểm sâu, không điểm danh bề mặt. Phủ **cả tập và mọi trạng thái liên quan** — không lấy mẫu. Ưu tiên quét xác định, theo chương trình chạm **mọi** mục (ví dụ parity khóa EN/VI, phủ lỗ, và quét rò trên mọi template; probe computed-style và overflow ở mọi breakpoint qua harness `_audit/` dùng `__dcSetProps` cho ngôn ngữ và postMessage `__dc_theme` cho theme), rồi thêm xác nhận visual hoặc export đại diện. Vài ảnh chụp là bằng chứng, không phải chứng minh. Không tuyên bố đã kiểm vì “spot-check” khi kiểm đủ là khả thi; nếu kiểm đủ thật sự không khả thi, nói rõ và nêu cái đã và chưa phủ. Ngôn ngữ, theme, và trạng thái responsive mỗi cái một lượt — một ngôn ngữ, chiều rộng, hoặc theme render sạch không phải bằng chứng cho cái khác.
+
+## Bất biến
+
+| Bất biến | Giá trị |
+|---|---|
+| Khẩu hiệu | *Turn Your Will Into Real* / *Hiện Thực Hoá Ý Chí* |
+| Thương hiệu chính | Umber `#45210E` |
+| Accent chính | Ochre `#F4BA17` |
+| Giọng | ấm · thẳng · thật · tôn trọng (cả bốn cùng lúc) |
+| Ngôn ngữ | Việt Nam trước; mọi chuỗi UI gửi cặp EN + VN |
+| Sàn a11y | APCA Lc ≥ 75 chữ thân; không bao giờ gỡ focus ring; mục tiêu chạm ≥ 44px |
+| Trục | Theme × Element × Language × Style (độc lập) |
+| Gói Style | liquid-glass (gói duy nhất; vắng ≡ mặc định) |
+
+Một accent mỗi bề mặt. Trạng thái ngữ nghĩa và chỉ báo focus tổ hợp (viền text-primary + hào quang ochre) không bao giờ elemental. Lumi luôn vàng trong mọi element.
+
+## Tài liệu đã xuất bản
+
+Docs operator và entrance là markdown chuẩn trong kho. Chúng **cũng** bắt buộc trên site Storybook sống: mọi trang được theo dõi phải xuất hiện trên thanh bên Docs và trong Thư viện tài liệu (`docs/viewer.html`). Tài liệu chỉ có trong repo mà không nằm trong tập xuất bản đó là lỗi, bị `docs-storybook-coverage` và `docs-link-check` bắt.

package/docs/vi/figma.md

@@ -1,5 +1,7 @@
 # Figma / Tokens Studio — ghi chú
 
+
+Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 ## Những gì ship trong repo
 - Design tokens dạng CSS + DTCG (`tokens/tokens.dtcg.json`) kèm mirror native Swift/Kotlin/Flutter.
 - UI kits dưới `ui_kits/` là tái tạo HTML giữ pixel-faithful theo doctrine brand (kit Thổ-first; demo trục ở Storybook / Atomic View).

package/docs/vi/live-hub.md

@@ -1,5 +1,7 @@
 # Live hub = Storybook
 
+Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
+
 ## Quyết định
 
 **Storybook là live interactive hub duy nhất** cho operator trên `design.cyberskill.world`. Không có trang Live View riêng và không còn shell dashboard HTML làm sản phẩm. Production **`/`** là Storybook.
@@ -8,7 +10,7 @@
 
 | Nhóm | Vai trò |
 |---|---|
-| **Docs** | Hướng dẫn MDX công khai (consuming, deploy, conventions, styles, products, schema, Figma, contrast, voice, axes) |
+| **Docs** | Docs operator đã xuất bản: **Start** (Introduction, README, SKILL, Contributing, llms, Library) · **Guides** (consuming, grant, deploy, schema, conventions, styles, products, Figma, contrast, storybook, live-hub, runbook phát hành, benchmark, …) · **Maintainers** (học thuyết, decisions, CI/CD, quality gates, sync). MDX curated cộng một mục sidebar mỗi trang tracked. EN·VI qua Thư viện tài liệu (`/docs/viewer.html`) |
 | **Foundations** | Colors, typography, spacing, elevation, motion, elements |
 | **Components** | Thư viện CSF đầy đủ |
 | **Release Notes** | Prose sản phẩm curated (**không CHANGELOG.md**) |

package/docs/vi/products.md

@@ -1,6 +1,6 @@
 # Product registry — ánh xạ element
 
-> **Đã khóa / locked** (Th7 2026). Registry product → element chuẩn cho agent và kit. **Không** invent ánh xạ product → element mới; thêm hoặc đổi hàng chỉ qua quyết định maintainer trong `docs/decisions.md`.
+> **Đã khóa / locked** (Th7 2026). Registry product → element chuẩn cho agent và kit. **Không** invent ánh xạ product → element mới; thêm hoặc đổi hàng chỉ qua quyết định maintainer trong `docs/decisions.md`. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 **Nguồn chân lý.** Ánh xạ sản phẩm portfolio CyberSkill sang pack element Ngũ Hành. Một element mỗi sản phẩm; accent phụ chỉ trong gradient wash theo Tương sinh.
 

package/docs/vi/quality-gates.md

@@ -1,10 +1,10 @@
 # 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.
+Mọi quality gate deterministic trong hệ thống, nó assert gì, tiêu chí pass, hard hay advisory, và chạy ở đâu. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 **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 — 40 gates trong `_audit/run.html`
+## Fast board — 42 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).
 
@@ -16,6 +16,8 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 | 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 |
+| Docs Storybook coverage | `_audit/docs-storybook-coverage.html` | HTML sống: catalog đã xuất bản + `/docs/**` + viewer + file entrance; title `index.json` Storybook khi có (không fetch `.storybook/` / `stories/` chưa xuất bản). Node twin: nguồn CSF/MDX + `staticDirs` | 0 trang / mục viewer thiếu (`__docssbcoverage`) | Hard | Fast board CI + unit twin |
+| Docs link check | `_audit/docs-link-check.html` | HTML sống: markdown đã xuất bản + link viewer resolve; không path đã nghỉ. Node twin còn quét `href`/`src` MDX chưa xuất bản | 0 link trong-repo gãy (`__docslinkcheck`) | Hard | Fast board CI + unit twin |
 | 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 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 |
@@ -77,6 +79,8 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 |---|---|---|---|---|---|
 | 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 |
+| Docs Storybook coverage (Node twin) | `_audit/ci/test-docs-storybook-coverage.mjs` | Docs tracked + entrance + doctrine mỗi cái có title story Storybook và path viewer; `staticDirs` gồm `docs/` | Exit 0 | Hard | Unit test |
+| Docs link check (Node twin) | `_audit/ci/test-docs-link-check.mjs` | Link tương đối trong-repo của tập xuất bản bắt buộc resolve; path đã nghỉ không là href sống | 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 ≥1 trục trong {size, variant, state} tồn tại (≥28 primary đủ điều kiện) | Mọi assert pass (exit 0) | Hard | Unit test |
 | Axe coverage | `_audit/ci/test-axe-coverage.mjs` | `NAMES` fixture ≡ `listPublicComponents()`; axe-smoke nạp fixture khoá inventory | Mọi assert pass (exit 0) | Hard | Unit test |

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 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**).
+Đ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**). Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 ## Patch — `@cyberskill/design@1.1.1`
 

package/docs/vi/release-runbook.md

@@ -1,6 +1,6 @@
 # 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.
+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. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 ## Kích hoạt
 

package/docs/vi/storybook.md

@@ -1,6 +1,6 @@
 # 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.
+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. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 ## URL
 
@@ -20,7 +20,7 @@ Storybook **10** là **site sản phẩm** cho operator trên `design.cyberskill
   - Mọi option enum `size` / `variant` rời rạc được mount trong story họ matrix
   - `FullMatrix` khi ≥1 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 (light · dark · **system**) × Element × Language × Style (cùng trục với template / Atomic View). Element liệt kê **đủ 15** pack Ngũ Hành (`tokens.elements` / EL map template / Storybook toolbar) — không phải tập con. Pack Style duy nhất là **liquid-glass**.
-- **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
+- **Docs/** tài liệu operator đã xuất bản — lồng **Start / Guides / Maintainers**, MDX curated cho trang traffic cao, một story sidebar mỗi trang markdown tracked, và iframe Thư viện tài liệu `/docs/viewer.html` (EN·VI). Prose chuẩn vẫn là `docs/*.md`; Storybook là bề mặt đọc sống. **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, 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)
@@ -40,7 +40,7 @@ Storybook **10** là **site sản phẩm** cho operator trên `design.cyberskill
 | ESM (bundler) | `_esm/react.mjs` (mặc định / `@cyberskill/design/react`) |
 | ESM (browser legacy) | `_esm/cs.mjs` (`@cyberskill/design/legacy`) |
 | Tokens | `tokens/*` |
-| Claude Design | `templates/**/*.dc.html` |
+| DC-capable authoring | `templates/**/*.dc.html` |
 
 ## Lệnh
 

package/docs/vi/sync.md

@@ -1,10 +1,10 @@
-# Repo ↔ Claude Design — round-trip fidelity & đồng bộ hai chiều
+# Repo ↔ môi trường authoring — round-trip fidelity & đồng bộ hai chiều
 
-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 GitHub (`cyberskill-official/design`) là **nguồn chân lý**. Session compiler (ví dụ 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. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 ## 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:
+**Trong session compiler DC-capable — 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`)
@@ -13,15 +13,15 @@ Repo GitHub (`cyberskill-official/design`) là **nguồn chân lý**. Session Cl
 - **`_esm/react.mjs`** — entry React bundler-native (export package mặc định; React peer). Regenerated qua `npm run build:react-entry`.
 - **`_esm/cs.mjs`** — entry ESM browser / no-build legacy (`@cyberskill/design/legacy`). 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`)
+- `README.md`, `CONTRIBUTING.md`, `SKILL.md`, `docs/doctrine.md`, shim host (`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.
+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/`. Artifact compile đã commit (`_ds_bundle.js`, `_ds_manifest.json`, `_adherence.oxlintrc.json`, `dist/styles.min.css`, `DESIGN.md`) là một phần hợp đồng consumer — giữ trong cây và regenerate bằng npm script đã ghi, đừng coi chúng là disposable.
 
-**Ở 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.
+**Ở 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 không-compiler 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 DC.
 
 ## Đồ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*:
+Session compiler có thể **đọc/copy từ** GitHub nhưng thườ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:

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

@@ -1,6 +1,6 @@
 # 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.
+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. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 **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ó.
 

package/docs/viewer.html

@@ -43,12 +43,23 @@
   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}
+  html.embed body{grid-template-columns:1fr}
+  html.embed aside{display:none}
+  html.embed main{padding:24px 32px}
   @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}
+    html.embed main{padding:18px 16px}
   }
-</style></head>
+</style>
+<script>
+(function(){
+  var q=new URLSearchParams(location.search);
+  if(q.get('embed')==='1'||q.get('chrome')==='0') document.documentElement.classList.add('embed');
+})();
+</script>
+</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>
@@ -58,13 +69,13 @@
 <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/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']]]
+ ['Guides',[['docs/consuming.md','Consuming & upgrading'],['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/doctrine.md','Doctrine'],['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/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']]]
+ ['Maintainer',[['docs/doctrine.md','Học thuyết'],['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; }