@cyberskill/design 1.2.0 → 1.3.9

package/docs/doctrine.md

@@ -0,0 +1,51 @@
+# Doctrine
+
+Normative rules for extending and verifying the CyberSkill Design System. Host-specific files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`) are shims that point here. Consumers start at `SKILL.md` and the Storybook **Docs** sidebar at `design.cyberskill.world`. Published on Storybook **Docs** at `design.cyberskill.world`.
+
+## When to use
+
+- You are adding or changing an element, variant, icon, component, token role, language, or template pattern.
+- You are verifying a change before calling it done.
+- You need the immutables that must never be redesigned ad hoc.
+
+## Non-goals
+
+This file is not a changelog, not a product registry, and not a consume guide. Product → element mappings live in `docs/products.md`. Adoption paths live in `docs/consuming.md`.
+
+## Expansion rule
+
+When **anything** in this system grows, update **every deliverable in the same change**:
+
+1. Tokens and source (`tokens/`, component `.jsx` + `.d.ts` + `.prompt.md`).
+2. Specimen cards (guidelines plus the component group card) **and any related guideline pages**.
+3. **All** templates (tweak enums, EL/EX maps, swept accents).
+4. UI kits — Thổ-faithful kit pages; axis demos via Storybook toolbar and Atomic View (Identity Lab is retired).
+5. Docs: README (counts follow the compiler), `SKILL.md`, this file, `docs/conventions.md`, **and every related document the change touches** (kit READMEs, `docs/products.md`, `docs/contrast-report.md` regeneration after token changes). Publish the same pages through Storybook Docs (see `docs/storybook.md`). **`VERSION` auto-bumps on push to `main`** from Conventional Commits (`.github/workflows/version.yml` → tag `v*` → `npm-publish.yml`); the owner may still force a bump via `Release-As:` / `workflow_dispatch`. **Do not maintain a changelog file** — LAUNCHED at **1.1.0**; pin tracks `VERSION`. Continuity is git history plus curated Release Notes.
+6. Browsable and health surfaces: a new or changed component gets an Atomic View story in `guidelines/atomic-view.html` (plus a live playground if it has tweakable props — `_audit/story-coverage.html` enforces the story) and behavior coverage in `_audit/component-behavior-test.html` if interactive; any new axis, tool, or tab is wired into `_audit/index.html` and Storybook **Status** (full-bleed `_audit/run.html` — `dashboard.html` is redirect-only); the matching deterministic gate is added or updated (`contrast-guard` for new colour rules, `token-contract` plus the contrast matrix for tokens, `story-coverage` for components, `docs-storybook-coverage` for published docs).
+
+**Gate:** `check_design_system` clean (compiler sessions only) **plus** `_audit/run.html` (all fast gates) green **plus** `docs-consistency` green **plus** a grep for the old enum or list to prove nothing was left behind. On a portable clone, the equivalent is the fast board plus `npm run test:unit`.
+
+Documented scope boundaries (doctrine, not gaps): UI-kit pages remain Thổ-faithful recreations; bilingual EN·VN covers emails plus team, legal, and finance docs (client and media collateral is EN-first); text never sits on the mid-tone `-accent`.
+
+## Verification depth
+
+Deep checks, never surface spot-checks. Cover the **whole set and every relevant state** — not a sample. Prefer deterministic, programmatic scans that touch **every** item (for example EN/VI key-parity, hole-coverage, and leak scan across all templates; computed-style and overflow probes at every breakpoint via the `_audit/` harnesses using `__dcSetProps` for language and the `__dc_theme` postMessage for theme), then add representative visual or export confirmation on top. A few screenshots are evidence, not proof. Never call work verified because it was “spot-checked” when a complete check is feasible; if a full check truly is not feasible, say so explicitly and state what was and was not covered. Language, theme, and responsive states each get their own pass — one language, width, or theme rendering cleanly is not evidence for the others.
+
+## Immutables
+
+| Immutable | Value |
+|---|---|
+| Slogan | *Turn Your Will Into Real* / *Hiện Thực Hoá Ý Chí* |
+| Primary brand | Umber `#45210E` |
+| Primary accent | Ochre `#F4BA17` |
+| Voice | warm · direct · honest · respectful (all four at once) |
+| Language | Vietnamese-first; every UI string ships an EN + VN pair |
+| Accessibility floor | APCA Lc ≥ 75 body text; focus rings never removed; ≥ 44px touch targets |
+| Axes | Theme × Element × Language × Style (independent) |
+| Style pack | liquid-glass (sole pack; absent ≡ default) |
+
+One accent per surface. Semantic statuses and the composite focus indicator (text-primary contour + ochre halo) are never elemental. Lumi stays golden in every element.
+
+## Published documentation
+
+Operator and entrance docs are canonical as markdown in this repository. They are **also** required on the live Storybook site: every tracked page must appear in the Docs sidebar and in the Documentation Library (`docs/viewer.html`). Repo-only documentation that is not in that published set is a defect, caught by `docs-storybook-coverage` and `docs-link-check`.

package/docs/figma.md

@@ -1,5 +1,7 @@
 # Figma / Tokens Studio notes
 
+
+Published on Storybook **Docs** at `design.cyberskill.world`.
 ## What ships in-repo
 - Design tokens in CSS + DTCG (`tokens/tokens.dtcg.json`) with native Swift/Kotlin/Flutter mirrors.
 - UI kits under `ui_kits/` are HTML recreations that stay pixel-faithful to the brand doctrine (Thổ-first kits; axis demos in Storybook / Atomic View).

package/docs/live-hub.md

@@ -1,5 +1,7 @@
 # Live hub = Storybook
 
+Published on Storybook **Docs** at `design.cyberskill.world`.
+
 ## Decision
 
 **Storybook is the single live interactive hub** for operators on `design.cyberskill.world`. There is no separate Live View page and no separate HTML dashboard product shell. Production **`/`** is Storybook.
@@ -8,7 +10,7 @@
 
 | Group | Role |
 |---|---|
-| **Docs** | Public MDX guides (consuming, deploy, conventions, styles, products, schema, Figma, contrast, voice, axes) |
+| **Docs** | Published operator docs: **Start** (Introduction, README, SKILL, Contributing, llms, Library) · **Guides** (consuming, grant, deploy, schema, conventions, styles, products, Figma, contrast, storybook, live-hub, release runbook, benchmark, …) · **Maintainers** (doctrine, decisions, CI/CD, quality gates, sync). Curated MDX plus one sidebar entry per tracked page. EN·VI via the Documentation Library (`/docs/viewer.html`) |
 | **Foundations** | Colors, typography, spacing, elevation, motion, elements |
 | **Components** | Full CSF library |
 | **Release Notes** | Curated product prose (**no CHANGELOG.md**) |

package/docs/products.md

@@ -1,6 +1,6 @@
 # Product registry — element mapping
 
-> **Locked** (Jul 2026). Canonical product → element registry for agents and kits. Do **not** invent new product → element assignments; add or change rows only via a maintainer decision in `docs/decisions.md`.
+> **Locked** (Jul 2026). Canonical product → element registry for agents and kits. Do **not** invent new product → element assignments; add or change rows only via a maintainer decision in `docs/decisions.md`. Published on Storybook **Docs** at `design.cyberskill.world`.
 
 **Source of truth.** Maps CyberSkill portfolio products to Ngũ Hành element packs. One element per product; secondary accents only in gradient washes along Tương sinh.
 

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) plus the `token-provenance` job. Every browser gate publishes a verdict global (`window.__*`) that the headless runners read.
+**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 — 39 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,8 +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` | 0 mismatched claims, 0 blacklist hits, VERSION sync + stamp + routing 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 |
@@ -35,7 +38,7 @@ Benchmark principles (WCAG · APCA · OKLCH · DTCG · CDS doctrine + style expa
 | Package exports integrity | `_audit/package-exports-integrity.html` | Every `package.json` `files` entry and every `module`/`types`/`style`/`exports` target exists; every entry-point target is covered by `files` (pack-safe); dual entries — `_esm/react.mjs` (default / `./react`, React peer) + `_esm/cs.mjs` (`./legacy`) — are ESM-shaped and their re-exports ⊆ the bundle header's exposed exports | 0 missing / uncovered / unknown (`__pkgexports`) | Hard | Fast board CI |
 | Component children | `_audit/component-children-test.html` | Void-element components (Checkbox, Radio, Switch, SearchField, NumberField, Slider, Divider, TextField) mount with stray children without throwing React #137 | 0 throws (`__result.anyThrew === false`) | Hard | Fast board CI |
 | Component behavior | `_audit/component-behavior-test.html` | 79 real interaction assertions — every interactive public primary with a user-driven contract (overlays, forms, AI gates, shell chrome, media/copy) plus toast-over-dialog depth; display-only primaries excluded by design | 79/79 assertions pass (`__behavior`) | Hard | Fast board CI |
-| A11y interactions | `_audit/a11y-gate.html` | Focus management (Dialog/Drawer trap + restore + Escape), roving tabindex, combobox `aria-activedescendant`, role/label contracts, plus open-state Esc/focus for Cascader · TreeSelect · Tour · HoverCard · ContextMenu | All keyboard/ARIA assertions pass (`__a11y`) | Hard | Fast board CI |
+| A11y interactions | `_audit/a11y-gate.html` | Focus management (Dialog/Drawer trap + restore + Escape), roving tabindex, combobox `aria-activedescendant`, Mentions APG + Sortable move buttons (hard-fail), role/label contracts, plus open-state Esc/focus for Cascader · TreeSelect · Tour · HoverCard · ContextMenu | All keyboard/ARIA assertions pass (`__a11y`) | Hard | Fast board CI |
 | A11y CSSOM | `_audit/a11y-harness.html` | Every interactive `.cs-*` control meets its documented touch-target floor under coarse pointer; focus-ring, reduced-motion, and contrast rules proven in source CSS | 0 floor violations, all source proofs found (`__a11ycss`) | Hard | Fast board CI |
 | Template schema v2 | `_audit/template-schema-test.html` | Every `content-schema.json` sidecar validates against the JSON Schema, every declared slot id resolves to a real `{{ hole }}` in its template, and every template exposing an authorable **content** hole ships a sidecar (axis/control-flow and boolean tweak holes excluded — see `docs/template-schema-v2.md`) | 0 invalid sidecars, 0 dangling slot ids, 0 hole-driven templates without a sidecar (`__schemav2`) | Hard | Fast board CI |
 | Support runtime identity | `_audit/support-runtime-identity.html` | All `templates/*/support.js` copies (one per template, 84) are byte-identical: sha-256 via SubtleCrypto, exactly one unique hash, copy count == manifest template count | 1 unique hash, count match (`__supportid`) | Hard | Fast board CI |
@@ -65,13 +68,20 @@ Benchmark principles (WCAG · APCA · OKLCH · DTCG · CDS doctrine + style expa
 | Token provenance | `_audit/ci/check-token-provenance.mjs` | `tokens/native/` + `tokens/provenance.json` are in lockstep with `tokens/tokens.dtcg.json` (same sha-256 drift authority as the token-pipeline gate) | Exit 0 on hash match | Hard | CI `token-provenance` job |
 | Bundle freshness (authority) | `_audit/ci/check-bundle-freshness.mjs` | The committed `_ds_bundle.js` was built from the component sources as they exist now — full source discovery (walks `components/`, `ui_kits/`, root sources), so new/deleted files are caught too, which the browser row cannot do | Exit 0, 0 drifted/new/deleted sources | Hard | CI `node-prechecks` job |
 | DESIGN.md freshness | `scripts/generate-design-md.mjs --check` | The root `DESIGN.md` byte-equals a fresh regeneration from DTCG + manifest + `VERSION` | Exit 0 on byte match | Hard | CI `node-prechecks` job |
+| styles.min.css freshness | `scripts/flatten-styles.mjs --check` | Committed `dist/styles.min.css` byte-equals flatten of `styles.css` + tokens/base (FIND-026) | Exit 0 on byte match | Hard | CI `node-prechecks` job |
+| contrast-report freshness | `scripts/generate-contrast-report.mjs --check` | EN + VI contrast reports match regeneration from element packs (FIND-026) | Exit 0 on byte match | Hard | CI `node-prechecks` job |
+| Manifest coverage | `_audit/ci/check-manifest-coverage.mjs` | Shipped `templates/` + `.card.html` + startingPoints match `_ds_manifest.json` (allowlisted: `_vendor`, `schema`, `email-safe`) | Exit 0 | Hard | CI `node-prechecks` + unit |
+| Storybook build + freshness | `npm run build:storybook` + `test-storybook-freshness.mjs --require` | Storybook builds in CI; stamp matches `stories/` + `.storybook/` (FIND-074 / FIND-075) | Exit 0 | Hard | CI `storybook-build` job |
 
-## Unit tests — `npm run test:unit` (13)
+## Unit tests — `npm run test:unit`
 
 | Test | File | What it asserts | Pass criterion | Type | Where it runs |
 |---|---|---|---|---|---|
 | 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 |
@@ -82,9 +92,11 @@ Benchmark principles (WCAG · APCA · OKLCH · DTCG · CDS doctrine + style expa
 | React entry | `_audit/ci/test-react-entry.mjs` | Dual package exports (`.` / `./react` → `_esm/react.mjs`, `./legacy` → `_esm/cs.mjs`); `package.json` version equals `VERSION`; React peerDeps; react.mjs has no CDN/bundle bridge and re-exports match the bundle header; `generate-react-entry --check` green | All assertions pass (exit 0) | Hard | Unit test |
 | Element packs | `_audit/ci/test-element-packs.mjs` | `tokens/elements.css` + JSON/JS/DTCG mirrors byte-equal regeneration from `tokens/element-seeds.json` | `generate-element-packs --check` exit 0 | Hard | Unit test |
 | i18n builtins + doc/font residuals | `_audit/ci/test-i18n-builtins.mjs` | No hardcoded EN UI literals outside the registry path; 0 doc-palette hexes in templates; 0 raw font-size px in `base/` | Exit 0 | Hard | Unit test |
-| Storybook static freshness | `_audit/ci/test-storybook-freshness.mjs` | When `storybook-static/` exists, `.cs-freshness.json` `sourceHash` matches `stories/` + `.storybook/` (UX-030). Absent static tree skips. | Exit 0 | Hard | Unit test |
+| Manifest coverage | `_audit/ci/check-manifest-coverage.mjs` | Disk templates/cards/startingPoints ⊆ manifest (`email-safe` allowlisted) | Exit 0 | Hard | Unit test |
+| Pack hygiene | `_audit/ci/test-pack-hygiene.mjs` | Tarball excludes `docs/tasks|audits|plans|status`; includes notices + fonts + `_vendor/` (FIND-064) | Exit 0 | Hard | Unit test |
+| CI verdict selftest | `_audit/ci/ci-verdict.mjs --selftest` | Soft-skip vs success annotation helper (FIND-095) | Exit 0 | Hard | Unit test |
 
-The `test:unit` suite is wired into the CI workflow as part of the July 2026 hardening change (it previously only ran locally).
+The `test:unit` suite is wired into the CI workflow as part of the July 2026 hardening change (it previously only ran locally). Storybook freshness runs in `storybook-build` with `--require` (not skipped in CI).
 
 ## Audit probe suite — `npm run test:audit-probe`
 
@@ -92,20 +104,20 @@ Promoted entry for UX audit proxies (`_audit/ci/audit-probe-suite.mjs`): unit su
 
 ## Sync / distribution jobs (soft-skip)
 
-Soft-skip means the job exits 0 with a report when secrets/plan/API cannot complete the real write — **not** that Code Connect or Figma Variables are live. npm CI publish uses Trusted Publishing; soft-skip covers auth/conflict honesty. Treat remaining maintainer tasks in `docs/decisions.md` as the open list (Code Connect deferred; consumer grant is in `docs/consumer-grant.md`). Storybook `FullMatrix` is required for every public primary with ≥1 of {size enums, variant enums, state keys} — shared helpers in `stories/lib/matrix.jsx`.
+Soft-skip means the job exits 0 with a report when secrets/plan/API cannot complete the real write — **not** that Code Connect or Figma Variables are live. Soft-skip writes `$GITHUB_STEP_SUMMARY` and emits a distinct CI annotation (`::error::` on schedule/main, `::warning::` elsewhere) so it is never identical silent green to live success (FIND-095). npm CI publish uses Trusted Publishing; soft-skip covers **already-published** and true non-GHA `missing_secrets` only — auth/404/402 on GHA release fail closed (see `docs/release-runbook.md`). Treat remaining maintainer tasks in `docs/decisions.md` as the open list (Code Connect deferred; consumer grant is in `docs/consumer-grant.md`). Storybook `FullMatrix` is required for every public primary with ≥1 of {size enums, variant enums, state keys} — shared helpers in `stories/lib/matrix.jsx`.
 
 | Job | Script / workflow | What it asserts | Soft-skip when | Where it runs |
 |---|---|---|---|---|
 | Figma Variables | `_audit/ci/push-figma-variables.mjs` + `figma-variables-push` job | Secrets open the file; optional Variables write | Soft-skip when secrets missing (same honesty as Code Connect) or non-Enterprise / missing `file_variables:*` scopes / API **403** after secrets are present. Soft-skip ≠ live sync | `main` push + manual |
 | Code Connect | `_audit/ci/code-connect-publish.mjs` + `code-connect` job | Config + 105 mappings; optional publish | Missing `FIGMA_TOKEN`/`FIGMA_FILE_KEY` or API 403/404/429 | PR + `main` + manual |
-| npm publish | `_audit/ci/npm-publish.mjs` + `npm-publish.yml` | Pack-safe `files`/`exports`; `npm publish` via OIDC Trusted Publishing (tokens disallowed on package) | Auth / 403 / 404 / EOTP / version conflict | `workflow_dispatch` / `v*` tags |
+| npm publish | `_audit/ci/npm-publish.mjs` + `npm-publish.yml` | Pack-safe `files`/`exports` (incl. `_vendor/`); `npm publish` via OIDC Trusted Publishing (tokens disallowed on package); post-publish `npm view` version **and** `dist-tags.latest === VERSION` (FIND-094) | Soft-skip: `already_published` / non-GHA `missing_secrets` only. **Fail on GHA release:** ENEEDAUTH / 404 / 402 / 403 / EOTP / missing registry presence or wrong `latest` | `workflow_dispatch` / `v*` tags |
 | Native store | `_audit/ci/native-store-dry-run.mjs` + `native-store.yml` | Fastlane scaffolds + metadata; signed-release secrets check | Missing `ASC_*` / `PLAY_SERVICE_ACCOUNT_JSON` (submit always disabled) | PR + `main` (paths) + manual |
 
-## Registry consumer smoke (hard)
+## Registry consumer smoke (fail-closed)
 
 | Job | Script / workflow | What it asserts | Pass criterion | Where it runs |
 |---|---|---|---|---|
-| npm-hello smoke | `examples/npm-hello` + `npm-hello-smoke` job | Public registry install of `@cyberskill/design@1.1.1` resolves package name + exports (`npm install` + `npm run smoke`; local pack proof if VERSION not on registry yet) | Exit 0 (**hard fail** once published; soft-skip pack proof if VERSION not on registry yet) | Path-filtered push/PR + nightly + manual |
+| npm-hello smoke | `examples/npm-hello` + `npm-hello-smoke` job | Public registry install of `@cyberskill/design@$VERSION` resolves package name + exports (`npm install` + `npm run smoke`) | Exit 0 only when VERSION is on the registry (**fail-closed**, FIND-087). Local-pack proof only if fork sets `NPM_HELLO_ALLOW_LOCAL_PACK=true` | Path-filtered push/PR + nightly + manual |
 
 ## July 2026 hardening — delivered
 

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

@@ -0,0 +1,78 @@
+# 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. Published on Storybook **Docs** at `design.cyberskill.world`.
+
+## Trigger
+
+| Path | When |
+|------|------|
+| **Auto** | Push to `main` with Conventional Commits → `version.yml` bumps `VERSION`, stamps artifacts, commits `chore(release): X.Y.Z`, tags `vX.Y.Z` |
+| **Force** | `Release-As: X.Y.Z` trailer on a commit, or `workflow_dispatch` on `version.yml` with a level |
+| **Manual publish** | `workflow_dispatch` on `npm-publish.yml` (also runs on `v*` tags) |
+
+Never push/deploy/merge without an explicit operator instruction when operating as an agent.
+
+## What fires (happy path)
+
+```
+main push (feat/fix/…)
+  → version.yml  (bump VERSION + stamps + bundle + tag vX.Y.Z)
+  → npm-publish.yml  (OIDC Trusted Publishing; post-publish version + dist-tags.latest)
+  → Vercel (host)  (build:site → .vercel-static; headers from vercel.json)
+  → sbom.yml on tag  (CycloneDX artifact)
+```
+
+Scorecard runs on a weekly schedule + `main` pushes (`.github/workflows/scorecard.yml`).
+
+## Success signals
+
+1. GitHub Actions: `version` green; `npm-publish` green (**not** soft-skip) with registry presence **and** `dist-tags.latest === VERSION` (FIND-094).
+2. `npm view @cyberskill/design version` **and** `npm view @cyberskill/design dist-tags.latest` both equal root `VERSION`.
+3. `npm-hello-smoke` green on the tip (fail-closed registry install of that VERSION — FIND-087).
+4. Production: `/` is Storybook; `/VERSION` is plain semver; `/_audit/run.html` fast board green.
+5. Artifacts: `cyclonedx-sbom` on the tag run; Scorecard SARIF on Security / Actions artifacts.
+6. Post-deploy Health protocol in `docs/deploy.md`.
+
+## Historical unpublished tags (do not backfill)
+
+| Tag | Status | Operator action |
+|-----|--------|-----------------|
+| `v1.2.1` | Historical git tag; **not** published to npm as `latest` | Leave unpublished |
+| `v1.3.0` | Historical git tag; **not** published to npm as `latest` | Leave unpublished |
+| `v1.3.1` (current tip) | **Publish target** when operator instructs | Publish **only** `1.3.1` as `dist-tags.latest` |
+
+Do **not** publish `1.2.1` or `1.3.0` to close registry drift — close FIND-102 by publishing **`1.3.1` only** (operator-gated). npm `latest` may still read `1.2.0` until that publish lands.
+
+## Failure / recovery
+
+| Symptom | Action |
+|---------|--------|
+| `npm-publish` 403 / EOTP / ENEEDAUTH / 404 / 402 on tag or `workflow_dispatch` | **Fail-closed.** Fix Trusted Publisher binding for repo **`cyberskill-official/design`** (FIND-088) / 2FA / OIDC; re-run on the tag. Soft-skip must **not** report success for these. |
+| Soft-skip `already_published` | Expected no-op — confirm registry; do not treat as success if you intended a new version. |
+| Soft-skip `missing_secrets` | Expected only **off** GitHub Actions (local). On GHA release this is a hard fail. |
+| `version.yml` push soft-warn | Set `PUSH_TOKEN` or allow Actions to push past branch protection (see `docs/ci-cd.md`). |
+| `npm-hello-smoke` red (VERSION missing on registry) | Expected until publish lands (FIND-087). Follow **Incident: unpublished release** below — do not set `NPM_HELLO_ALLOW_LOCAL_PACK` on the canonical repo. |
+| Nightly `design-system-gates` red | GitHub notifies the default workflow subscribers; see “Scheduled-job alerting” below. Re-run `workflow_dispatch`. |
+| Partial Vercel deploy | Re-run deploy; follow Health re-run protocol; do not invent live header claims without `curl -sSI`. |
+
+## Incident: unpublished release (FIND-100 / FIND-101 / FIND-107)
+
+Use when git/`VERSION`/site are ahead of npm `dist-tags.latest` (e.g. tip `1.3.1`, registry still `1.2.0`).
+
+1. **Confirm skew** — `cat VERSION`; `npm view @cyberskill/design version`; `npm view @cyberskill/design dist-tags.latest`; note git tags `v1.2.1` / `v1.3.0` / `v1.3.1` as historical vs publish target.
+2. **Do not** treat a green `npm-publish` soft-skip (or a green `npm-hello` local-pack proof) as evidence the version is public — smoke is fail-closed; publish auth errors hard-fail on GHA.
+3. **Fix Trusted Publisher** if needed — npm package settings must list org/repo **`cyberskill-official/design`**, workflow **`npm-publish.yml`**, and the correct environment (FIND-088). Classic `NPM_TOKEN` is disallowed. CI uses a clean OIDC userconfig (no empty `_authToken` from `actions/setup-node`) so Trusted Publishing can exchange the GitHub OIDC token.
+4. **Operator-gated publish** — only after an explicit instruction: re-run `npm-publish.yml` on tag **`v1.3.1`** (or `workflow_dispatch` at that tip). Publish target is **`1.3.1` only**; do not backfill `1.2.1` / `1.3.0`.
+5. **Verify** — `npm view @cyberskill/design@1.3.1 version` and `dist-tags.latest` both `1.3.1`; re-run `npm-hello-smoke` (or wait for the next gates run) to green.
+6. **Rollback / deprecate (if a bad version reached `latest`)** — `npm deprecate @cyberskill/design@<bad> "…"` and/or `npm dist-tag add @cyberskill/design@<good> latest`. npm does not allow unpublishing recent public versions in the normal case — prefer deprecate + retag `latest`. Site/Vercel rollback is independent (`docs/deploy.md`).
+
+## Scheduled-job alerting (area 27)
+
+- Nightly cron `0 3 * * *` on `design-system-gates.yml`.
+- On schedule failure the workflow’s `notify-schedule-failure` job (`needs` every scheduled job — FIND-108) emits an Actions error annotation and fails when `contains(needs.*.result, 'failure')`, which triggers **GitHub’s native workflow-failure email** to repository watchers / the last actor as configured under Settings → Notifications.
+- Optional: add a repo Actions variable / secret for Slack webhook later; do not require it for green CI.
+- Operators should watch the Actions badge in `docs/ci-cd.md` and enable “Actions” notification for failed workflows.
+
+## Product vs CyberOS
+
+See `docs/decisions.md` §13. The npm package and portable tree are the product; `.cyberos/` is orchestration only.

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-system`) 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-system`) is the **source of truth**
 - **`_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,29 +1,30 @@
 # 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.
 
 ## Badge
 
-[![Design System Gates](https://github.com/cyberskill-official/design-system/actions/workflows/design-system-gates.yml/badge.svg)](https://github.com/cyberskill-official/design-system/actions/workflows/design-system-gates.yml)
+[![Design System Gates](https://github.com/cyberskill-official/design/actions/workflows/design-system-gates.yml/badge.svg)](https://github.com/cyberskill-official/design/actions/workflows/design-system-gates.yml)
 
 ## Những gì đã nối (`.github/workflows/design-system-gates.yml`)
 
 1. **`fast-gates`** — `npm ci` + Playwright Chromium cache, serve repo, mở `_audit/run.html` headless (`_audit/ci/run-gates.mjs`), fail khi hard-gate fail. Upload import-report khi fail. Hàng mới trên board (hardening Th7 2026 thêm 8: token-format-parity, version-stamp, support-runtime-identity, package-exports-integrity, template-lang-parity, dtcg-typing, design-md-parity, bundle-freshness) được nhận tự động — runner đọc `window.__run`, không phải danh sách gate phía job.
 2. **`token-provenance`** — kiểm Node không trình duyệt: natives + `provenance.json` khớp sha-256 nguồn DTCG.
 3. **`unit-tests`** — `npm run test:unit` (11 contract test Node thuần; nối vào CI bởi hardening Th7 2026 — trước đó chỉ local). Gồm `test-element-packs` (freshness `node scripts/generate-element-packs.mjs --check`).
-4. **`node-prechecks`** — authority Node không trình duyệt: `_audit/ci/check-bundle-freshness.mjs` (nguồn chân lý bundle-freshness — khám phá source đầy đủ gồm file mới/xóa; hàng board chỉ re-hash file ghi trong header) và `scripts/generate-design-md.mjs --check` (`DESIGN.md` gốc byte-equals regeneration).
+4. **`node-prechecks`** — authority Node không trình duyệt: `_audit/ci/check-bundle-freshness.mjs` (nguồn chân lý bundle-freshness — khám phá source đầy đủ gồm file mới/xóa; hàng board chỉ re-hash file ghi trong header), `scripts/generate-design-md.mjs --check` (`DESIGN.md` gốc byte-equals regeneration), `scripts/flatten-styles.mjs --check` + `scripts/generate-contrast-report.mjs --check` (FIND-026), và `_audit/ci/check-manifest-coverage.mjs` (FIND-078).
+4b. **`storybook-build`** — `npm run build:storybook` rồi `test-storybook-freshness.mjs --require` (FIND-074 / FIND-075). Storybook gãy sẽ fail CI trước deploy.
 5. **`docs-consistency-blocker`** — merge blocker `docs-consistency` + `bilingual-parity`.
 6. **`whole-set-audits`** — quyết định B của owner: mọi push/PR, cộng nightly `0 3 * * *` và `workflow_dispatch` (responsive + language + theme overflow, ~15–20 phút).
 7. **`figma-variables-push`** — trên push `main` + thủ công. **`FIGMA_TOKEN` / `FIGMA_FILE_KEY` trống → soft-skip** (exit 0 + report — cùng trung thực với Code Connect). Quyết định A (non-Enterprise): Variables REST cũng **soft-skip khi API 403** (và lỗi plan/scope liên quan) sau khi secret chứng minh mở file. Soft-skip ≠ sync Variables live. Xem `docs/figma.md`.
 8. **`code-connect`** — trên PR + `main` + thủ công. Quyết định 1C: dry-run luôn (config + 105 mapping); publish soft-skip khi thiếu `FIGMA_TOKEN` / `FIGMA_FILE_KEY` hoặc API 403/404/429. Xem `docs/figma.md`.
-9. **`regenerate-tokens`** (pull request) + **`regenerate-tokens-push`** (push `main` / schedule / thủ công) — path filter phủ element seeds/packs (`element-seeds.json`, `elements.css`, mirror JSON/JS/DTCG, `generate-element-packs.mjs`) cộng natives / `VERSION`. Regenerate chạy `npm run tokens:elements` rồi `node _audit/ci/generate-native-tokens.mjs`. Trên **pull request** job chạy với `contents: read`, không bao giờ push, và **exit 1** khi có drift: chạy cả hai ở local rồi commit. Chỉ job song sinh push/schedule/thủ công giữ `contents: write` và auto-commit với `DS_PUSH_TOKEN` (hoặc `github.token`).
-10. **`npm-hello-smoke`** — chứng minh consumer registry: `cd examples/npm-hello && npm ci && npm run smoke` (**hard fail**; package public). Path-filtered trên push/PR khi `examples/npm-hello/**`, bề mặt publish package, hoặc workflow này đổi; luôn chạy trên schedule / `workflow_dispatch`.
+9. **`regenerate-tokens`** (pull request) + **`regenerate-tokens-push`** (push `main` / schedule / thủ công) — path filter phủ element seeds/packs (`element-seeds.json`, `elements.css`, mirror JSON/JS/DTCG, `generate-element-packs.mjs`) cộng natives / `VERSION`. Regenerate chạy `npm run tokens:elements` rồi `node _audit/ci/generate-native-tokens.mjs`. Trên **pull request** job chạy với `contents: read`, không bao giờ push, và **exit 1** khi có drift: chạy cả hai ở local rồi commit (freshness bắt buộc trên PR). Chỉ job song sinh push/schedule/thủ công giữ `contents: write` và có thể auto-commit với `PUSH_TOKEN` (hoặc `github.token`). Auto-commit **không** dùng `[skip ci]` — tip được push phải chạy lại bảng gate (FIND-021 / TASK-IMP-008); lần chạy thứ hai deterministic là no-op.
+10. **`npm-hello-smoke`** — chứng minh consumer registry cho `@cyberskill/design@$VERSION` (**fail-closed**, FIND-087): `examples/npm-hello` → `npm install` từ registry + `npm run smoke`. Nếu VERSION **không** có trên registry, job **fail** (không soft-skip pack proof trên `cyberskill-official/design`). Fork chỉ được opt-in pack local khi đặt biến repo **`NPM_HELLO_ALLOW_LOCAL_PACK=true`**. Path-filtered trên push/PR khi `examples/npm-hello/**`, bề mặt publish package, hoặc workflow này đổi; luôn chạy trên schedule / `workflow_dispatch`.
 
-Workflow riêng **`version`** (`.github/workflows/version.yml`): mỗi push lên `main`, bump `VERSION` theo Conventional Commits + stamp artifact; commit `chore(release): X.Y.Z`, push, và tạo tag `vX.Y.Z`. Bỏ qua chính commit release (an toàn vòng lặp). Owner có thể force level qua `workflow_dispatch` hoặc trailer `Release-As:`. Cần `contents: write` (cùng pattern `DS_PUSH_TOKEN` như `regenerate-tokens-push` nếu branch protection chặn `github.token`).
+Workflow riêng **`version`** (`.github/workflows/version.yml`): mỗi push lên `main`, bump `VERSION` theo Conventional Commits + stamp artifact; rồi regen natives/provenance hash và `npm run build:bundle` để tip sạch gate; commit `chore(release): X.Y.Z`, push, và tạo tag `vX.Y.Z`. Bỏ qua chính commit release (an toàn vòng lặp). Owner có thể force level qua `workflow_dispatch` hoặc trailer `Release-As:`. Cần `contents: write`. Checkout dùng `secrets.PUSH_TOKEN || github.token` — nếu branch protection yêu cầu status checks (hoặc chặn `github.token`), đặt repository secret **`PUSH_TOKEN`** (fine-grained PAT, Contents: Read and write); không thì bump tính được nhưng push soft-warn và không land.
 
-Workflow riêng **`npm-publish`** (`.github/workflows/npm-publish.yml`): `workflow_dispatch` + tag `v*` (thường do `version.yml` tạo); pack dry-run luôn; publish qua **npm Trusted Publishing (OIDC)** (`id-token: write`, không `NPM_TOKEN` trên bước publish). Soft-skip khi auth / 403 / 404 / EOTP / conflict phiên bản. License **UNLICENSED**. Trusted Publisher trên npmjs phải khớp filename workflow `npm-publish.yml`. Publishing access package: **Require 2FA and disallow tokens** (OIDC vẫn chạy; token classic bị từ chối).
+Workflow riêng **`npm-publish`** (`.github/workflows/npm-publish.yml`): `workflow_dispatch` + tag `v*` (thường do `version.yml` tạo); pack dry-run luôn; publish qua **npm Trusted Publishing (OIDC)** (`id-token: write`, không `NPM_TOKEN` trên bước publish). Soft-skip chỉ **`already_published`** và `missing_secrets` thật sự **ngoài GHA**. Trên tag / `workflow_dispatch`, **ENEEDAUTH** / **404** / **402** / **403** / **EOTP** **fail closed**. Sau publish assert `npm view @cyberskill/design@VERSION` **và** `dist-tags.latest === VERSION` (FIND-094). License **UNLICENSED**. Trusted Publisher trên npmjs phải khớp filename workflow `npm-publish.yml` cho repo **`cyberskill-official/design`** (FIND-088). Publishing access package: **Require 2FA and disallow tokens** (OIDC vẫn chạy; token classic bị từ chối).
 
 Workflow riêng **`native-store`** (`.github/workflows/native-store.yml`): PR + `main` (path-filtered) + `workflow_dispatch`; dry-run scaffold luôn; kiểm signed-release soft-skip khi thiếu `ASC_KEY_ID` / `ASC_ISSUER_ID` / `ASC_KEY_P8` / `PLAY_SERVICE_ACCOUNT_JSON`. **Không bao giờ submit** lên App Store / Play — sample vẫn là sample. Xem `examples/native/README.md`.
 
@@ -42,16 +43,18 @@ Node **22** trên runner (tránh deprecation action Node 20). Cache key Playwrig
 
 ## Quyền auto-commit token
 
-Chỉ `regenerate-tokens-push` yêu cầu `permissions: contents: write`; job song sinh cho pull request `regenerate-tokens` giữ `contents: read` và checkout không lưu credential, nên PR không bao giờ kích hoạt push của bot. Nếu org khóa default token read-only, đặt repository secret `DS_PUSH_TOKEN` (fine-grained PAT, Contents read/write) hoặc mở write tại org Actions settings. Xem ghi chú trước trong git history / org settings.
+`regenerate-tokens-push` và `version.yml` yêu cầu `permissions: contents: write` và checkout với `secrets.PUSH_TOKEN || github.token`. Job song sinh pull request `regenerate-tokens` giữ `contents: read` và không bao giờ push. Nếu ruleset/branch protection yêu cầu status checks trước khi push (hoặc khóa default Actions token), đặt repository secret **`PUSH_TOKEN`** (fine-grained PAT, Contents: Read and write trên repo này) hoặc cho phép GitHub Actions bypass ruleset. Không có thì bot push soft-warn và exit 0; drift nội dung vẫn hard-fail qua `token-provenance` / fast-gates / `node-prechecks`.
 
-## Branch protection (khuyến nghị)
+## Branch protection (khuyến nghị) — NV-18.1 ngoài repo
 
-Require status checks trên `main` trước merge:
+**NV-18.1 (assessment):** check nào **bắt buộc** trước khi merge `main`, admin có bị ràng buộc không, và CODEOWNERS / review / conversation-resolution có được enforce — đều là **cài đặt GitHub, không nằm trong repo**. Trạng thái quan sát từ clone: **không biết / xác nhận ngoài băng**. Không bịa giá trị ruleset live từ YAML workflow.
+
+**Khuyến nghị** (chỉ tài liệu — áp dụng trong GitHub Settings → Branches / Rulesets, hoặc `gh api` admin):
 
 - `fast-gates`
 - `docs-consistency-blocker`
 
-Tùy chọn: `whole-set-audits` (dài). Cấu hình dưới repo **Settings → Branches** hoặc qua `gh api` (admin).
+Tùy chọn: `whole-set-audits` (dài).
 
 ## Chạy local
 
@@ -74,11 +77,11 @@ node _audit/ci/generate-native-tokens.mjs
 - **Hàng visual / component baseline side-by-side** — chỉ advisory (drift đánh giá bằng mắt). So sánh `%` pixel Playwright là gate **hard** (job `pixel-diff` + hàng Pixel CI trên board).
 - **Figma Variables** — soft-skip khi thiếu secret (cùng trung thực với Code Connect) hoặc write Variables gặp non-Enterprise / API **403**; report artifact ghi lại skip. Soft-skip ≠ sync live.
 - **Code Connect publish** — soft-skip khi thiếu secret hoặc API 403/404/429 (Quyết định 1C).
-- **npm publish** — Trusted Publishing (OIDC) trên `npm-publish.yml`; soft-skip khi auth / conflict (Quyết định 1C).
+- **npm publish** — Trusted Publishing (OIDC) trên `npm-publish.yml`; soft-skip khi `already_published` / `missing_secrets` ngoài GHA; trên GHA release **ENEEDAUTH** / **404** / **402** / **403** / **EOTP** fail closed + kiểm version **và** `dist-tags.latest` sau publish (Quyết định §7 / FIND-020 / FIND-094).
 - **Native store signed release** — soft-skip khi thiếu `ASC_*` / `PLAY_SERVICE_ACCOUNT_JSON` (Quyết định 1C); submit store vẫn tắt.
-- **npm-hello registry smoke** — **hard fail** (`examples/npm-hello` → `npm ci` + `npm run smoke`); chứng minh đường install public `@cyberskill/design` (không soft-skip).
+- **npm-hello registry smoke** — **fail-closed** (`examples/npm-hello` → install registry + `npm run smoke`); thiếu `@cyberskill/design@$VERSION` thì job fail (FIND-087). Pack proof local chỉ opt-in trên fork (`NPM_HELLO_ALLOW_LOCAL_PACK`).
 
-Job `figma-variables-push` hay `code-connect` xanh — và do đó badge hay hàng Status xanh — chỉ có nghĩa job exit 0; nó **không** chứng minh sync Figma live, vì soft-skip và publish thật nhìn từ ngoài giống hệt nhau. Mở report artifact của run (`figma-push-report.json` / `code-connect-report.json`) để biết cái nào đã xảy ra.
+Job `figma-variables-push` hay `code-connect` vẫn exit 0 khi soft-skip (Quyết định 1C), nhưng FIND-095 làm outcome hiện trên trang run công khai qua `$GITHUB_STEP_SUMMARY` kèm annotation riêng (`::error::` trên schedule/main, `::warning::` nơi khác) — soft-skip không còn xanh im lặng giống publish thật. Report artifact (`figma-push-report.json` / `code-connect-report.json`) vẫn mang chi tiết.
 
 ## Soft-skip dry-run (local)
 

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
 
@@ -19,10 +19,13 @@ CyberSkill cấp cho **CyberSkill** (công ty và các team kỹ thuật sản p
 
 Package vẫn **UNLICENSED**. Cài từ npm registry **không** tự cấp quyền redistribution. Redistribution ngoài các sản phẩm trên — gồm publish fork, đổi license, hoặc ship package như dependency của sản phẩm bên thứ ba không liên quan — cần **grant viết thêm** ghi trong file này (hoặc văn bản thay thế).
 
+**Ngoại lệ bên thứ ba:** font OFL trong `fonts/`, runtime MIT trong `_vendor/`, và các asset liệt kê ở `THIRD-PARTY-NOTICES.md` giữ license **upstream**. Khẳng định UNLICENSED và grant này **không** thay thế các điều khoản đó; người redistribute phải tuân `fonts/OFL.txt` và file notices.
+
 ## Ghi chú phạm vi
 
 - **Clone / subtree / link tĩnh** repo này cho cùng các sản phẩm trên được cover giống npm install.
 - **Tooling chỉ-host** (Storybook, `_audit/`) không nằm trong tarball npm và không redistribution theo grant này.
+- **Notices bên thứ ba:** xem `THIRD-PARTY-NOTICES.md` và `fonts/OFL.txt` ở root.
 - Thêm sản phẩm CyberSkill mới: cập nhật `docs/products.md` (+ VI) qua quyết định maintainer, rồi thêm hàng sản phẩm tại đây trong cùng change.
 - Duyệt **team/client bên ngoài**: thêm stanza grant có ngày bên dưới (team/org, sản phẩm đã nêu, liên hệ). Không invent ánh xạ product → element tại đây — giữ ở `docs/products.md`.