Publish Thai VC ARF 2.0 DRAFT 0 in Docusaurus

.agents/skills/vcdoc-arf-sync/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: vcdoc-arf-sync
+description: >
+  How to sync Thai VC ARF content from vc-document into the vcdoc Docusaurus
+  site. Covers the directory layout (docs/thai-vc-arf + docs/en/thai-vc-arf,
+  which replaced the old docs/trust-guide) and the required HTML->MDX comment
+  conversion. Use when importing/copying ARF markdown from vc-document, when a
+  sync reintroduces raw HTML comments or a duplicate docs/th/thai-vc-arf/, or
+  when the build fails with MDX "Unexpected character `!`" errors.
+license: MIT
+---
+
+# vcdoc ARF sync & format conversion
+
+The vcdoc site (this repo) publishes the Thai VC ARF. The canonical source of
+truth is the `vc-document` repo. Content is copied from vc-document into this
+repo, but vc-document's files are NOT Docusaurus-ready as-is: they use a
+different directory layout and raw HTML comments. Both must be fixed on import.
+
+## Directory layout
+
+vcdoc is a SINGLE-locale site (`defaultLocale: 'th'`, `locales: ['th']`,
+`routeBasePath: '/'`). Thai content lives FLAT at the docs root.
+
+English is still SUPPORTED — but as a literal `docs/en/thai-vc-arf/` folder
+served under `/en/`, not as a Docusaurus i18n locale. It holds a one-page
+English summary (not a full translation), linked from the navbar
+("VC stack (EN)" -> `/en/thai-vc-arf/minimal-interoperability-reference`).
+Never delete `docs/en/` when working on the single-locale layout:
+
+```
+docs/
+  thai-vc-arf/                   # Thai chapters (22 .md files + images/)
+    _category_.json              # label + link.slug "/"  (homepage = Thai index)
+    00-minimal-interoperability-reference.md
+    ... (chapters 1-16)
+    images/
+  en/
+    _category_.json
+    thai-vc-arf/
+      _category_.json
+      00-minimal-interoperability-reference.md
+```
+
+vc-document uses a locale-prefixed layout (`docs/th/thai-vc-arf/` and
+`docs/en/thai-vc-arf/`). The sync must STRIP the `th/` prefix for Thai content:
+
+- `vc-document/th/thai-vc-arf/*`  ->  `docs/thai-vc-arf/*`   (drop the `th/`)
+- `vc-document/en/thai-vc-arf/*`  ->  `docs/en/thai-vc-arf/*` (keep the `en/`)
+
+### Directory rename: trust-guide -> thai-vc-arf
+
+- The OLD content directory was `docs/trust-guide/` (the original Trust
+  Framework manual). It is gone — replaced by `thai-vc-arf`.
+- vc-document still versions the legacy trust-guide as
+  `versioned_docs/version-2026-09/trust-guide/`. vcdoc does NOT use Docusaurus
+  versioning — never copy `versioned_docs/`, `versioned_sidebars/`,
+  `versions.json`, `i18n/`, or vc-document's `src/theme/` swizzles into vcdoc.
+
+### Forbidden: the locale-prefixed duplicate
+
+Do NOT create `docs/th/thai-vc-arf/`. vc-document keeps Thai under a `th/`
+locale prefix; vcdoc does not. Copying that path as-is produces a duplicate of
+every Thai file (the exact bloat this skill exists to prevent). The canonical
+Thai path in THIS repo is `docs/thai-vc-arf/`.
+
+## Format conversion (required for the build)
+
+vc-document files use HTML comments; Docusaurus MDX cannot compile them, and
+the build fails with:
+
+```
+MDX compilation failed ... Unexpected character `!` (U+0021) before name
+```
+
+Two changes are needed on import:
+
+1. Convert top-level HTML comments `<!-- ... -->` to MDX comments `{/* ... */}`.
+2. Add frontmatter to Thai `.md` files (the English file gets NO frontmatter):
+
+```
+---
+description: "<H1 text> — Thai VC ARF 2.0 DRAFT 0"
+---
+```
+
+The `description` is the file's first `# ` heading plus the suffix
+` — Thai VC ARF 2.0 DRAFT 0`. Exception: `README.md` uses the fixed value
+`Thai VC ARF — 2.0 DRAFT 0 — Thai VC ARF 2.0 DRAFT 0`.
+
+### Comment conversion rules (must be exact)
+
+Convert ONLY top-level comments. Comments do not nest; a `<!-- ... -->` that
+appears INSIDE an outer comment is literal text and must stay as `<!-- ... -->`.
+
+Do NOT touch:
+
+- Mermaid sequence arrows `-->>` (they contain `-->` as a prefix substring).
+- Flow text such as `P1 --> P2 --> P3`.
+- Literal comment examples inside comments, e.g. the README bullet
+  `` `<!-- pdf page N -->` ``.
+
+Reference implementation (balanced, non-nested):
+
+```python
+def convert_comments(text):
+    depth = 0
+    out, i = [], 0
+    while i < len(text):
+        if text.startswith('<!--', i):
+            out.append('{/*' if depth == 0 else '<!--')
+            depth += 1
+            i += 4
+        elif text.startswith('-->', i):
+            out.append('*/}' if depth == 1 else '-->')
+            depth = max(0, depth - 1)
+            i += 3
+        else:
+            out.append(text[i])
+            i += 1
+    assert depth == 0, 'unbalanced comments'
+    return ''.join(out)
+```
+
+Then for Thai files: `'---\ndescription: "{desc}"\n---\n\n' + convert_comments(raw)`.
+For the English file: `convert_comments(raw)` only (no frontmatter).
+
+## Verification
+
+After any sync or format change, confirm:
+
+```
+npm run build       # must exit 0
+npm run typecheck   # must exit 0
+```
+
+- Homepage `/` must serve the Thai index titled "Thai VC ARF — 2.0 DRAFT 0".
+- Thai docs must be at `/thai-vc-arf/...` (NOT `/th/thai-vc-arf/...`).
+- Broken-link/anchors warnings are EXPECTED: the ARF markdown references
+  vc-document-only files (`../research/*`, `../policy/*`, `../public-site/*`,
+  `../../00-glossary.md`) that are not present here. The config intentionally
+  uses `onBrokenLinks: 'warn'`.
+
+## Known gotchas
+
+- A prior sync did two things wrong: it copied content to BOTH
+  `docs/th/thai-vc-arf/` and `docs/thai-vc-arf/`, AND it overwrote converted
+  files with raw HTML-comment versions. Check for both after every sync.
+- `grep -c '-->'` over-counts: mermaid `-->>` arrows contain `-->`. Use the
+  balanced converter above, not a naive string replace.

.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+# Validate the Docusaurus site on every push and pull request.
+#
+# This is the CI half of the pipeline (separate from deploy.yml, which is CD).
+# It typechecks, builds, statically validates the build output, and then runs
+# browser-based E2E tests that verify locale rendering and client-side mermaid
+# hydration — both of which only happen in a real browser.
+#
+# Best practices applied:
+#   - npm ci (not npm install) for reproducible installs from package-lock.json
+#   - Node version pinned to match "engines.node" (>=20) in package.json
+#   - npm cache via actions/setup-node, plus a Playwright browser cache
+#   - concurrency group so a new push cancels the stale in-flight run
+#   - build/ and Playwright artifacts uploaded for inspection on failure
+name: Validate Docusaurus
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+  pull_request:
+
+# Read-only checkout is all this workflow needs.
+permissions:
+  contents: read
+
+# Cancel the previous run on the same ref when a newer push arrives.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Build site
+        run: npm run build
+
+      # Static checks on build/: every doc generated, locale layout, no raw
+      # HTML comments, mermaid blocks present in source.
+      - name: Validate build output
+        run: npm run validate:build
+
+      # Cache the Playwright browser binaries (keyed on the lockfile so a dep
+      # bump invalidates it). Saves ~150MB download on subsequent runs.
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+
+      # --with-deps installs the OS libraries Chromium needs on Ubuntu.
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      # Serves build/ and verifies locale rendering + mermaid hydration.
+      - name: Browser E2E tests
+        run: npm run test:e2e
+
+      - name: Upload site build
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: site-build
+          path: build
+          retention-days: 7
+
+      - name: Upload Playwright report on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7

.gitignore

@@ -8,6 +8,10 @@
 .docusaurus
 .cache-loader
 
+# Playwright
+/test-results/
+/playwright-report/
+
 # Misc
 .DS_Store
 .env.local

README.md

@@ -1,6 +1,6 @@
 # VC Document
 
-> เอกสารและมาตรฐาน **Verifiable Credential (VC)** โดย ETDA — คู่มือ Trust Framework ของระบบ VC Ecosystem ประเทศไทย
+> **Thai VC ARF — 2.0 DRAFT 0** กรอบแนวทางการทำงานร่วมกันของเอกสารรับรองดิจิทัลสำหรับประเทศไทย
 
 **🌐 เว็บไซต์ (อ่านเอกสารฉบับเต็ม):** **https://etda.github.io/vcdoc/**
 
@@ -10,25 +10,13 @@
 
 ## เกี่ยวกับโปรเจกต์นี้
 
-โปรเจกต์นี้คือเว็บไซต์เอกสาร (documentation site) ที่รวบรวม **คู่มือ Trust Framework** ของระบบ Verifiable Credential ในประเทศไทย
-อธิบายว่ากรอบความน่าเชื่อถือ (Trust Framework) ของ ETDA ทำให้ทุกฝ่ายในระบบ VC เชื่อใจกันได้อย่างไร
-ตั้งแต่การ **ออกเอกสารดิจิทัล (Issuance)** ไปจนถึงการ **แสดงเอกสารให้ผู้ตรวจสอบ (Presentation)**
-
-เนื้อหาแบ่งเป็น 9 ส่วนหลัก เรียงตามลำดับที่ควรอ่าน:
-
-| บท | หัวข้อ | เหมาะกับใคร |
-|----|--------|-------------|
-| 1 | Concepts & Roles — แนวคิดและบทบาท | ผู้เริ่มต้นทุกคน |
-| 2 | Architecture — สถาปัตยกรรมภาพรวม | ผู้เริ่มต้น / สถาปนิกระบบ |
-| 3 | Issuance Flow — ขั้นตอนการออกเอกสาร | นักพัฒนาฝั่งผู้ออกบัตร (Issuer) |
-| 4 | Presentation Flow — ขั้นตอนการแสดงเอกสาร | นักพัฒนาฝั่งผู้ตรวจสอบ (Verifier) |
-| 5 | Trust Infrastructure — โครงสร้างความน่าเชื่อถือ | นักพัฒนา / ผู้ดูแลระบบ |
-| 6 | Security & Privacy — ความปลอดภัยและความเป็นส่วนตัว | ทุกฝ่าย |
-| 7 | Governance & Conformance — การกำกับดูแลและการรับรอง | องค์กรที่ต้องการเข้าร่วมระบบ |
-| 8 | FAQ — คำถามที่พบบ่อย | ทุกคน |
-| 9 | Appendix — ภาคผนวก (สรุปกฎความปลอดภัย) | อ้างอิงเร็ว |
-
-> 💡 แนะนำ: ผู้เริ่มต้นอ่านบท 1–2 ก่อน, ผู้ออกบัตรเริ่มบท 3, ผู้ตรวจสอบเริ่มบท 4, องค์กรที่อยากเข้าร่วมดูบท 7
+เว็บไซต์นี้แสดง [Thai VC ARF ฉบับภาษาไทย](docs/thai-vc-arf/README.md) เป็นเนื้อหาหลัก ครอบคลุมบทสรุป บทที่ 1–16 และรูปประกอบ โดยแทนที่คู่มือ Trust Framework เดิมทั้งหมด
+
+- **เวอร์ชันเว็บไซต์:** `2.0 DRAFT 0` แสดงในเมนูเวอร์ชันของ Docusaurus
+- **ต้นทางบทภาษาไทย:** `vc-document/th/thai-vc-arf/`
+- [English summary](docs/en/thai-vc-arf/00-minimal-interoperability-reference.md) — คัดลอกจาก `vc-document/en/thai-vc-arf/`; แหล่งต้นทางมีบทสรุปภาษาอังกฤษหนึ่งหน้า ไม่ใช่คำแปลทุกบท
+
+ไฟล์ Markdown ที่นำเข้าปรับรูปแบบคอมเมนต์จาก HTML เป็น MDX เพื่อให้ Docusaurus สร้างเว็บไซต์ได้ โดยไม่แก้เนื้อหาหลักที่แสดงแก่ผู้อ่าน
 
 ## เทคโนโลยีที่ใช้
 

docs/en/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "English",
+  "position": 2
+}