@sungen/driver-data-factory 3.2.10-beta.13 → 3.2.10-beta.15

package/common/field-types/currency.yaml

@@ -1,20 +1,20 @@
 # Field-type: currency (money) — from common-checklist.xlsx (Input box · Currency).
 type: currency
-description: Số tiền — số nguyên/thập phân theo đơn vị tiền tệ; lưu ý leading-zero & giá trị 0.
+description: Money amount — integer/decimal per currency unit; watch leading-zero & the value 0.
 constraints:
   min: 0
   max: 999999999   # placeholder
-  decimalPlaces: 0 # placeholder (JPY=0, USD=2 …)
+  decimalPlaces: 0 # placeholder (JPY=0, USD=2 ...)
 valid:
-  - { id: CHK-CUR-01, value: "1000", note: "số tiền hợp lệ" }
-  - { id: CHK-CUR-02, value: "0", note: "giá trị 0 phải hiểu là 0, KHÔNG phải 'chưa nhập'" }
+  - { id: CHK-CUR-01, value: "1000", note: "valid amount" }
+  - { id: CHK-CUR-02, value: "0", note: "0 must mean 0, NOT 'not entered'" }
 boundary:
-  - { id: CHK-CUR-B1, gen: "Min / Min+1" }
-  - { id: CHK-CUR-B2, gen: "Max / Max-1" }
+  - { id: CHK-CUR-B1, gen: "min / min+1" }
+  - { id: CHK-CUR-B2, gen: "max / max-1" }
 invalid:
-  - { id: CHK-CUR-I1, gen: "chữ cái / ký tự lạ", reason: "không phải số", errorRef: M13 }
-  - { id: CHK-CUR-I2, gen: "Min-1 / Max+1", reason: "vượt biên", errorRef: M13 }
-  - { id: CHK-CUR-I3, value: "", reason: "rỗng (tuỳ spec)", errorRef: M02 }
+  - { id: CHK-CUR-I1, gen: "alphabetic / stray characters", reason: "not a number", errorRef: M13 }
+  - { id: CHK-CUR-I2, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
+  - { id: CHK-CUR-I3, value: "", reason: "empty (per spec)", errorRef: M02 }
 notes:
-  - "Kiểm tra riêng: leading zero (0100) có bị cắt mất không; format hiển thị dấu phân cách nghìn."
+  - "Check separately: leading zero (0100) not stripped; thousands separator display format."
 uses_security: [sqli]

package/common/field-types/email.yaml

@@ -1,8 +1,8 @@
-# Field-type: email — seeded from common-checklist.xlsx (Input box · Email) + phuong-phap §Nguồn-2.
+# Field-type: email — seeded from common-checklist.xlsx (Input box · Email) + the 4-source method.
 # errorRef (Mxx) are PLACEHOLDERS — the generator maps them onto the project's real message codes;
-# if the project spec has none, the value is marked as a chua-chot (open) point, not invented.
+# if the project spec has none, the value is marked as an open point, not invented.
 type: email
-description: Email half-width, format <local-part>@<domain>
+description: Half-width email, format <local-part>@<domain>.
 format: "<local-part>@<domain>"
 constraints:
   charset: half-width
@@ -13,18 +13,18 @@ valid:
   - { id: CHK-EMAIL-01, value: "user@example.com", note: "normal half-width" }
   - { id: CHK-EMAIL-02, value: "u.name+tag@sub.example.co.jp", note: "dotted local + subdomain" }
 boundary:
-  - { id: CHK-EMAIL-B1, gen: "local@ đúng maxLocal", note: "local part = max (64)" }
-  - { id: CHK-EMAIL-B2, gen: "local@ maxLocal-1", note: "local part = max-1" }
-  - { id: CHK-EMAIL-B3, gen: "chuỗi tổng = maxTotal", note: "total length = max (255)" }
+  - { id: CHK-EMAIL-B1, gen: "local part = maxLocal", note: "local part = max (64)" }
+  - { id: CHK-EMAIL-B2, gen: "local part = maxLocal-1", note: "local part = max-1" }
+  - { id: CHK-EMAIL-B3, gen: "total = maxTotal", note: "total length = max (255)" }
 invalid:
-  - { id: CHK-EMAIL-I1, value: "user@", reason: "thiếu domain", errorRef: M13 }
-  - { id: CHK-EMAIL-I2, value: "user@.com", reason: "dấu . sai vị trí", errorRef: M13 }
-  - { id: CHK-EMAIL-I3, value: "u@@b.com", reason: "hai dấu @", errorRef: M13 }
-  - { id: CHK-EMAIL-I4, value: "@example.com", reason: "thiếu local-part", errorRef: M13 }
-  - { id: CHK-EMAIL-I5, value: "ｕｓｅｒ@example.com", reason: "full-width character", errorRef: M39 }
-  - { id: CHK-EMAIL-I6, gen: "local > 64 ký tự", reason: "vượt maxLocal", errorRef: M13 }
-  - { id: CHK-EMAIL-I7, gen: "tổng > 255 ký tự", reason: "vượt maxTotal", errorRef: M13 }
-  - { id: CHK-EMAIL-I8, value: "", reason: "rỗng (required)", errorRef: M02 }
+  - { id: CHK-EMAIL-I1, value: "user@", reason: "missing domain", errorRef: M13 }
+  - { id: CHK-EMAIL-I2, value: "user@.com", reason: "dot in wrong position", errorRef: M13 }
+  - { id: CHK-EMAIL-I3, value: "u@@b.com", reason: "two @ signs", errorRef: M13 }
+  - { id: CHK-EMAIL-I4, value: "@example.com", reason: "missing local-part", errorRef: M13 }
+  - { id: CHK-EMAIL-I5, value: "ｕｓｅｒ@example.com", reason: "full-width characters", errorRef: M39 }
+  - { id: CHK-EMAIL-I6, gen: "local > maxLocal", reason: "exceeds maxLocal", errorRef: M13 }
+  - { id: CHK-EMAIL-I7, gen: "total > maxTotal", reason: "exceeds maxTotal", errorRef: M13 }
+  - { id: CHK-EMAIL-I8, value: "", reason: "empty (required)", errorRef: M02 }
 notes:
-  - "Chuẩn hoá: lowercase, NFKC, trim trước khi so khớp."
-  - "Soft-delete: nếu hệ thống gắn hậu tố vào email đã xoá mềm → test maxTotal THẤP hơn giới hạn cột DB để chừa chỗ hậu tố."
+  - "Normalize: lowercase, NFKC, trim before comparison."
+  - "Soft-delete: if a deleted email gets a suffix appended, test maxTotal LOWER than the DB column limit to leave room for the suffix."

package/common/field-types/jp/katakana.yaml

@@ -1,20 +1,20 @@
-# Field-type: Katakana name (JP-specific) — from phuong-phap §Nguồn-2 (kinh nghiệm đặc thù JP).
+# Field-type: Katakana name (JP-specific) — from the 4-source method (JP field-type experience).
 type: katakana
-description: Trường chỉ nhận Katakana (họ/tên kana trong hệ thống Nhật).
+description: Katakana-only field (kana name in Japanese systems).
 constraints:
   charset: "full-width Katakana only"
 valid:
-  - { id: CHK-KANA-01, value: "ヤマダ", note: "Katakana chuẩn" }
-  - { id: CHK-KANA-02, value: "ジョウジ", note: "có dakuten + trường âm hợp lệ" }
+  - { id: CHK-KANA-01, value: "ヤマダ", note: "standard Katakana" }
+  - { id: CHK-KANA-02, value: "ジョウジ", note: "valid dakuten + long-vowel mark" }
 boundary:
-  - { id: CHK-KANA-B1, gen: "đúng min / max độ dài" }
+  - { id: CHK-KANA-B1, gen: "min / max length" }
 invalid:
-  - { id: CHK-KANA-I1, value: "yamada", reason: "lẫn ký tự Latin", errorRef: M39 }
-  - { id: CHK-KANA-I2, value: "やまだ", reason: "lẫn Hiragana", errorRef: M39 }
-  - { id: CHK-KANA-I3, value: "山田", reason: "lẫn Kanji", errorRef: M39 }
-  - { id: CHK-KANA-I4, value: "ﾔﾏﾀﾞ", reason: "half-width kana (nếu spec chỉ nhận full-width)", errorRef: M39 }
-  - { id: CHK-KANA-I5, value: "ゝ々", reason: "ký tự lặp — có tiền lệ lỗi thật nhiều hệ thống", errorRef: M39 }
-  - { id: CHK-KANA-I6, value: "ャュョ", reason: "kana nhỏ đứng một mình / sai vị trí", errorRef: M39 }
+  - { id: CHK-KANA-I1, value: "yamada", reason: "Latin characters mixed in", errorRef: M39 }
+  - { id: CHK-KANA-I2, value: "やまだ", reason: "Hiragana mixed in", errorRef: M39 }
+  - { id: CHK-KANA-I3, value: "山田", reason: "Kanji mixed in", errorRef: M39 }
+  - { id: CHK-KANA-I4, value: "ﾔﾏﾀﾞ", reason: "half-width kana (if spec requires full-width)", errorRef: M39 }
+  - { id: CHK-KANA-I5, value: "ゝ々", reason: "iteration marks — real-world bug precedent in many systems", errorRef: M39 }
+  - { id: CHK-KANA-I6, value: "ャュョ", reason: "small kana standalone / wrong position", errorRef: M39 }
 notes:
-  - "Chú ý: kana nhỏ (ゃゅょ), trường âm (ー), dakuten/handakuten, half↔full-width kana."
+  - "Watch: small kana (ゃゅょ), long-vowel mark (ー), dakuten/handakuten, half<->full-width kana."
 uses_security: [sqli, xss]

package/common/field-types/number-float.yaml

@@ -1,20 +1,20 @@
 # Field-type: number (float) — from common-checklist.xlsx (Input box · Number_Float).
 type: number-float
-description: Số thập phân — chữ số + dấu thập phân; số chữ số phần lẻ theo spec.
+description: Decimal number — digits + decimal separator; decimal places per spec.
 constraints:
   min: 0.0          # placeholder
   max: 999999.99    # placeholder
   decimalPlaces: 2  # placeholder
 valid:
-  - { id: CHK-FLOAT-01, value: "123.45", note: "hợp lệ" }
-  - { id: CHK-FLOAT-02, value: "0.5", note: "phần nguyên = 0" }
+  - { id: CHK-FLOAT-01, value: "123.45", note: "valid" }
+  - { id: CHK-FLOAT-02, value: "0.5", note: "integer part = 0" }
 boundary:
-  - { id: CHK-FLOAT-B1, gen: "Min / Min+1" }
-  - { id: CHK-FLOAT-B2, gen: "Max / Max-1" }
-  - { id: CHK-FLOAT-B3, gen: "đúng số chữ số thập phân / thừa 1 chữ số" }
+  - { id: CHK-FLOAT-B1, gen: "min / min+1" }
+  - { id: CHK-FLOAT-B2, gen: "max / max-1" }
+  - { id: CHK-FLOAT-B3, gen: "exact decimal places / one extra digit" }
 invalid:
-  - { id: CHK-FLOAT-I1, gen: "chữ cái", reason: "không phải số", errorRef: M13 }
-  - { id: CHK-FLOAT-I2, gen: "format sai (nhiều dấu chấm, +/- sai vị trí)", reason: "format sai", errorRef: M13 }
-  - { id: CHK-FLOAT-I3, gen: "Min-1 / Max+1", reason: "vượt biên", errorRef: M13 }
-  - { id: CHK-FLOAT-I4, value: "", reason: "rỗng/multi-space (tuỳ spec)", errorRef: M02 }
+  - { id: CHK-FLOAT-I1, gen: "alphabetic characters", reason: "not a number", errorRef: M13 }
+  - { id: CHK-FLOAT-I2, gen: "wrong format (multiple dots, +/- wrong position)", reason: "wrong format", errorRef: M13 }
+  - { id: CHK-FLOAT-I3, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
+  - { id: CHK-FLOAT-I4, value: "", reason: "empty/multi-space (per spec)", errorRef: M02 }
 uses_security: [sqli]

package/common/field-types/number-integer.yaml

@@ -1,21 +1,21 @@
 # Field-type: number (integer) — from common-checklist.xlsx (Input box · Number_Integer).
 type: number-integer
-description: Số nguyên — chỉ chữ số, có thể có +/- ở vị trí hợp lệ.
+description: Integer — digits only, optional +/- in valid position.
 constraints:
-  min: 0          # placeholder theo spec
+  min: 0          # placeholder per spec
   max: 2147483647 # placeholder
 valid:
-  - { id: CHK-INT-01, value: "123", note: "chỉ số" }
-  - { id: CHK-INT-02, value: "-45", note: "có dấu - đầu (nếu spec cho phép âm)" }
+  - { id: CHK-INT-01, value: "123", note: "digits only" }
+  - { id: CHK-INT-02, value: "-45", note: "leading - (if spec allows negatives)" }
 boundary:
-  - { id: CHK-INT-B1, gen: "Min / Min+1" }
-  - { id: CHK-INT-B2, gen: "Max / Max-1" }
+  - { id: CHK-INT-B1, gen: "min / min+1" }
+  - { id: CHK-INT-B2, gen: "max / max-1" }
 invalid:
-  - { id: CHK-INT-I1, gen: "chữ cái", reason: "không phải số", errorRef: M13 }
-  - { id: CHK-INT-I2, gen: "số full-width (Japanese number)", reason: "full-width", errorRef: M39 }
-  - { id: CHK-INT-I3, gen: "+/- sai vị trí (giữa chuỗi)", reason: "format sai", errorRef: M13 }
-  - { id: CHK-INT-I4, gen: "Min-1 / Max+1", reason: "vượt biên", errorRef: M13 }
-  - { id: CHK-INT-I5, value: "", reason: "rỗng/multi-space (tuỳ spec)", errorRef: M02 }
+  - { id: CHK-INT-I1, gen: "alphabetic characters", reason: "not a number", errorRef: M13 }
+  - { id: CHK-INT-I2, gen: "full-width (Japanese) digits", reason: "full-width characters", errorRef: M39 }
+  - { id: CHK-INT-I3, gen: "+/- in wrong position (mid-string)", reason: "wrong format", errorRef: M13 }
+  - { id: CHK-INT-I4, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
+  - { id: CHK-INT-I5, value: "", reason: "empty/multi-space (per spec)", errorRef: M02 }
 notes:
-  - "leading zero (007) có bị cắt không; redundant spaces trước/sau phải xử lý đúng."
+  - "Check leading zero (007) is not stripped; redundant spaces before/after handled correctly."
 uses_security: [sqli]

package/common/field-types/password.yaml

@@ -1,30 +1,30 @@
-# Field-type: password — seeded from common-checklist.xlsx (Input box · Password) + phuong-phap example.
+# Field-type: password — from common-checklist.xlsx (Input box · Password).
 type: password
-description: Password — độ dài + thành phần ký tự theo spec; kèm show/hide + mask.
-format: "theo ràng buộc spec (min/max, ≥1 hoa/thường/số tuỳ dự án)"
+description: Password — length + character-class rules per spec; plus show/hide + mask.
+format: "per spec (min/max, >=1 upper/lower/digit as required)"
 constraints:
-  minLength: 7        # placeholder — ghi đè bằng min thật của spec dự án
+  minLength: 7        # placeholder — override with the project spec's real min
   maxLength: 20       # placeholder
-  requires: [uppercase, lowercase, digit]   # placeholder theo spec
+  requires: [uppercase, lowercase, digit]   # placeholder per spec
 uses_security: [sqli, xss]
 valid:
-  - { id: CHK-PW-01, value: "Passw0rd", note: "đủ hoa+thường+số, trong khoảng" }
-  - { id: CHK-PW-02, note: "alpha only / numeric only / mix — nếu spec cho phép" }
-  - { id: CHK-PW-03, note: "ký tự đặc biệt hợp lệ theo spec (vd ._@)" }
+  - { id: CHK-PW-01, value: "Passw0rd", note: "upper+lower+digit, in range" }
+  - { id: CHK-PW-02, note: "alpha only / numeric only / mix — if the spec allows" }
+  - { id: CHK-PW-03, note: "valid special characters per spec (e.g. ._@)" }
 boundary:
-  - { id: CHK-PW-B1, gen: "đúng minLength", note: "min (vd Aa1bcde = 7)" }
-  - { id: CHK-PW-B2, gen: "minLength+1", note: "min+1" }
-  - { id: CHK-PW-B3, gen: "đúng maxLength", note: "max" }
-  - { id: CHK-PW-B4, gen: "maxLength-1", note: "max-1" }
+  - { id: CHK-PW-B1, gen: "min length", note: "min (e.g. Aa1bcde = 7)" }
+  - { id: CHK-PW-B2, gen: "min+1", note: "min+1" }
+  - { id: CHK-PW-B3, gen: "max length", note: "max" }
+  - { id: CHK-PW-B4, gen: "max-1", note: "max-1" }
 invalid:
-  - { id: CHK-PW-I1, value: "", reason: "rỗng/multi-space (required)", errorRef: M02 }
-  - { id: CHK-PW-I2, gen: "< minLength", reason: "dưới độ dài tối thiểu", errorRef: M29 }
-  - { id: CHK-PW-I3, gen: "> maxLength", reason: "vượt độ dài tối đa", errorRef: M30 }
-  - { id: CHK-PW-I4, value: "passw0rd", reason: "thiếu chữ hoa", errorRef: M31 }
-  - { id: CHK-PW-I5, value: "PASSW0RD", reason: "thiếu chữ thường", errorRef: M32 }
-  - { id: CHK-PW-I6, value: "Password", reason: "thiếu chữ số", errorRef: M33 }
-  - { id: CHK-PW-I7, gen: "full-width Japanese", reason: "ký tự full-width", errorRef: M39 }
-  - { id: CHK-PW-I8, gen: "space before/after hoặc giữa", reason: "khoảng trắng thừa", errorRef: M13 }
+  - { id: CHK-PW-I1, value: "", reason: "empty/multi-space (required)", errorRef: M02 }
+  - { id: CHK-PW-I2, gen: "< min length", reason: "below minimum length", errorRef: M29 }
+  - { id: CHK-PW-I3, gen: "> max length", reason: "exceeds maximum length", errorRef: M30 }
+  - { id: CHK-PW-I4, value: "passw0rd", reason: "missing uppercase", errorRef: M31 }
+  - { id: CHK-PW-I5, value: "PASSW0RD", reason: "missing lowercase", errorRef: M32 }
+  - { id: CHK-PW-I6, value: "Password", reason: "missing digit", errorRef: M33 }
+  - { id: CHK-PW-I7, gen: "full-width Japanese", reason: "full-width characters", errorRef: M39 }
+  - { id: CHK-PW-I8, gen: "space before/after or inside", reason: "redundant whitespace", errorRef: M13 }
 notes:
-  - "Kiểm tra riêng: icon show/hide password (hiển thị + toggle mask↔unmask), ký tự mask đúng spec."
-  - "Confirm Password: kế thừa toàn bộ case của password + case (confirm == password) và (confirm != password → lỗi)."
+  - "Check separately: show/hide password icon (display + toggle mask<->unmask), mask symbol per spec."
+  - "Confirm Password: inherits all password cases + (confirm == password) and (confirm != password -> error)."

package/common/field-types/phone.yaml

@@ -1,23 +1,23 @@
 # Field-type: phone number — from common-checklist.xlsx (Input box · Phone number).
 type: phone
-description: Số điện thoại — chỉ số, cho phép () - + ở vị trí hợp lệ.
+description: Phone number — digits only, allows () - + in valid positions.
 constraints:
   charset: "digits + () - +"
-  minLength: 8      # placeholder theo spec
+  minLength: 8      # placeholder per spec
   maxLength: 15     # placeholder
 valid:
-  - { id: CHK-PHONE-01, value: "0987654321", note: "chỉ số" }
-  - { id: CHK-PHONE-02, value: "+84-90-1234567", note: "có + và - đúng vị trí" }
-  - { id: CHK-PHONE-03, value: "(028)38221234", note: "có () đúng vị trí" }
+  - { id: CHK-PHONE-01, value: "0987654321", note: "digits only" }
+  - { id: CHK-PHONE-02, value: "+84-90-1234567", note: "+ and - in valid positions" }
+  - { id: CHK-PHONE-03, value: "(028)38221234", note: "() in valid positions" }
 boundary:
-  - { id: CHK-PHONE-B1, gen: "đúng min / min+1" }
-  - { id: CHK-PHONE-B2, gen: "đúng max / max-1" }
+  - { id: CHK-PHONE-B1, gen: "min / min+1 length" }
+  - { id: CHK-PHONE-B2, gen: "max / max-1 length" }
 invalid:
-  - { id: CHK-PHONE-I1, gen: "ký tự cấm []:,;\"<>\\?", reason: "ký tự không hợp lệ", errorRef: M13 }
-  - { id: CHK-PHONE-I2, gen: "số Nhật (full-width)", reason: "ký tự full-width", errorRef: M39 }
-  - { id: CHK-PHONE-I3, gen: "chữ cái", reason: "không phải số", errorRef: M13 }
-  - { id: CHK-PHONE-I4, value: "090 123 4567", reason: "khoảng trắng giữa số", errorRef: M13 }
-  - { id: CHK-PHONE-I5, gen: "+/- không ở vị trí đầu; () sai vị trí", reason: "format sai", errorRef: M13 }
-  - { id: CHK-PHONE-I6, gen: "min-1 / max+1", reason: "vượt biên", errorRef: M13 }
-  - { id: CHK-PHONE-I7, value: "", reason: "rỗng/multi-space (tuỳ spec)", errorRef: M02 }
+  - { id: CHK-PHONE-I1, gen: "forbidden chars []:,;\"<>\\?", reason: "invalid characters", errorRef: M13 }
+  - { id: CHK-PHONE-I2, gen: "full-width (Japanese) digits", reason: "full-width characters", errorRef: M39 }
+  - { id: CHK-PHONE-I3, gen: "alphabetic characters", reason: "not a number", errorRef: M13 }
+  - { id: CHK-PHONE-I4, value: "090 123 4567", reason: "spaces between digits", errorRef: M13 }
+  - { id: CHK-PHONE-I5, gen: "+/- not first; () wrong position", reason: "wrong format", errorRef: M13 }
+  - { id: CHK-PHONE-I6, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
+  - { id: CHK-PHONE-I7, value: "", reason: "empty/multi-space (per spec)", errorRef: M02 }
 uses_security: [sqli]

package/common/field-types/postcode.yaml

@@ -1,16 +1,16 @@
 # Field-type: postcode / zipcode — from common-checklist.xlsx (Input box · Postcode/Zipcode).
 type: postcode
-description: Mã bưu chính — format theo vùng (JP 7 số, có thể có dấu -).
+description: Postal code — region-specific format (JP 7 digits, optional -).
 constraints:
-  format: "region-specific (vd JP: NNN-NNNN)"
+  format: "region-specific (e.g. JP: NNN-NNNN)"
   length: 7   # placeholder
 valid:
-  - { id: CHK-ZIP-01, value: "1500001", note: "7 số (JP)" }
-  - { id: CHK-ZIP-02, value: "150-0001", note: "có dấu - nếu spec cho phép" }
+  - { id: CHK-ZIP-01, value: "1500001", note: "7 digits (JP)" }
+  - { id: CHK-ZIP-02, value: "150-0001", note: "with - if the spec allows" }
 boundary:
-  - { id: CHK-ZIP-B1, gen: "đúng độ dài / độ dài-1 / +1" }
+  - { id: CHK-ZIP-B1, gen: "exact length / length-1 / +1" }
 invalid:
-  - { id: CHK-ZIP-I1, gen: "chữ cái / ký tự lạ", reason: "sai ký tự", errorRef: M13 }
-  - { id: CHK-ZIP-I2, gen: "sai format vùng", reason: "sai format", errorRef: M13 }
-  - { id: CHK-ZIP-I3, value: "", reason: "rỗng (tuỳ spec)", errorRef: M02 }
+  - { id: CHK-ZIP-I1, gen: "alphabetic / stray characters", reason: "invalid characters", errorRef: M13 }
+  - { id: CHK-ZIP-I2, gen: "wrong region format", reason: "wrong format", errorRef: M13 }
+  - { id: CHK-ZIP-I3, value: "", reason: "empty (per spec)", errorRef: M02 }
 uses_security: [sqli]

package/common/field-types/string.yaml

@@ -1,20 +1,20 @@
-# Field-type: string (text 1 dòng) — from common-checklist.xlsx (Input box · String).
+# Field-type: string (single line) — from common-checklist.xlsx (Input box · String).
 type: string
-description: Chuỗi 1 dòng — chấp nhận alnum, JP half/full-width, special, unicode, space.
+description: Single-line string — accepts alnum, JP half/full-width, special chars, unicode, spaces.
 constraints:
-  minLength: 1      # placeholder theo spec
+  minLength: 1      # placeholder per spec
   maxLength: 255    # placeholder
 uses_security: [sqli, xss]
 valid:
   - { id: CHK-STR-01, value: "Normal text 123", note: "alnum + space" }
-  - { id: CHK-STR-02, gen: "half-width Japanese", note: "半角ｶﾅ" }
+  - { id: CHK-STR-02, gen: "half-width Japanese", note: "ﾊﾟｶﾅ" }
   - { id: CHK-STR-03, gen: "full-width Japanese", note: "全角かな漢字" }
-  - { id: CHK-STR-04, gen: "special chars ~!@#$%^&*()_+{}:|<>?,./;'[]-=`", note: "ký tự đặc biệt hợp lệ" }
-  - { id: CHK-STR-05, gen: "unicode / emoji nếu spec cho phép" }
-  - { id: CHK-STR-06, gen: "copy-paste full-width JP", note: "phải xử lý đúng khi paste" }
+  - { id: CHK-STR-04, gen: "special chars ~!@#$%^&*()_+{}:|<>?,./;'[]-=`", note: "valid special characters" }
+  - { id: CHK-STR-05, gen: "unicode / emoji if the spec allows" }
+  - { id: CHK-STR-06, gen: "copy-paste full-width JP", note: "must handle paste correctly" }
 boundary:
-  - { id: CHK-STR-B1, gen: "đúng min / min+1" }
-  - { id: CHK-STR-B2, gen: "đúng max / max-1" }
+  - { id: CHK-STR-B1, gen: "min / min+1 length" }
+  - { id: CHK-STR-B2, gen: "max / max-1 length" }
 invalid:
-  - { id: CHK-STR-I1, value: "", reason: "rỗng/multi-space (success/fail tuỳ spec)", errorRef: M02 }
-  - { id: CHK-STR-I2, gen: "min-1 / max+1", reason: "vượt biên", errorRef: M13 }
+  - { id: CHK-STR-I1, value: "", reason: "empty/multi-space (success/fail per spec)", errorRef: M02 }
+  - { id: CHK-STR-I2, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }

package/common/security/broken-auth.yaml

@@ -1,9 +1,9 @@
 # Security payload bank: Broken authentication — from common-checklist.xlsx (Broken authentication).
 class: broken-auth
-description: Xác thực yếu — session/token/brute-force.
+description: Weak authentication — session/token/brute-force.
 payloads:
-  - { id: CHK-SEC-AUTH-01, technique: "brute force login không giới hạn", expect: "có lockout/captcha/rate-limit" }
-  - { id: CHK-SEC-AUTH-02, technique: "session không hết hạn sau logout / đổi mật khẩu", expect: "invalidate session cũ" }
-  - { id: CHK-SEC-AUTH-03, technique: "session fixation — dùng lại session id trước đăng nhập", expect: "cấp session mới sau login" }
-  - { id: CHK-SEC-AUTH-04, technique: "token đoán được / không hết hạn", expect: "token ngẫu nhiên mạnh, có TTL" }
-oracle: "Đăng nhập/duy trì phiên trái phép = lỗ hổng."
+  - { id: CHK-SEC-AUTH-01, technique: "unlimited brute-force login", expect: "lockout/captcha/rate-limit present" }
+  - { id: CHK-SEC-AUTH-02, technique: "session not expired after logout / password change", expect: "old session invalidated" }
+  - { id: CHK-SEC-AUTH-03, technique: "session fixation — reuse the pre-login session id", expect: "issues a new session after login" }
+  - { id: CHK-SEC-AUTH-04, technique: "guessable / non-expiring token", expect: "strong random token with a TTL" }
+oracle: "Unauthorized login / session persistence = a vulnerability."

package/common/security/idor.yaml

@@ -1,8 +1,8 @@
 # Security payload bank: IDOR — from common-checklist.xlsx (Insecure Direct Object Reference).
 class: idor
-description: Insecure Direct Object Reference — đổi id để truy cập tài nguyên của người khác.
+description: Insecure Direct Object Reference — change an id to access another user's resource.
 payloads:
-  - { id: CHK-SEC-IDOR-01, technique: "đổi id trên URL/param sang record của user khác", expect: "403/404, KHÔNG lộ dữ liệu người khác" }
-  - { id: CHK-SEC-IDOR-02, technique: "đoán id tuần tự (1,2,3…) trên API detail", expect: "kiểm tra quyền sở hữu, từ chối" }
-  - { id: CHK-SEC-IDOR-03, technique: "thao tác (edit/delete) resource ngoài quyền qua id", expect: "chặn ở server, không chỉ ẩn UI" }
-oracle: "Truy cập/sửa được dữ liệu ngoài quyền = lỗ hổng. Kỳ vọng: authorization check theo ownership phía server."
+  - { id: CHK-SEC-IDOR-01, technique: "change the id in URL/param to another user's record", expect: "403/404, does NOT leak the other user's data" }
+  - { id: CHK-SEC-IDOR-02, technique: "guess sequential ids (1,2,3...) on a detail API", expect: "checks ownership, rejects" }
+  - { id: CHK-SEC-IDOR-03, technique: "act (edit/delete) on a resource outside your scope via id", expect: "blocked server-side, not just hidden in the UI" }
+oracle: "Reading/modifying data outside your scope = a vulnerability. Expected: ownership authorization server-side."

package/common/security/input-validation.yaml

@@ -1,8 +1,8 @@
 # Security payload bank: Input validation — from common-checklist.xlsx (Input validation).
 class: input-validation
-description: Ràng buộc đầu vào phía server (không chỉ FE).
+description: Server-side input constraints (not just the front-end).
 payloads:
-  - { id: CHK-SEC-IV-01, technique: "vượt boundary khi FE bị bypass (gọi API trực tiếp)", expect: "server cũng chặn" }
-  - { id: CHK-SEC-IV-02, technique: "sai kiểu dữ liệu (string vào field số)", expect: "reject với lỗi hợp lệ" }
-  - { id: CHK-SEC-IV-03, technique: "control/null bytes, ký tự điều khiển", expect: "loại bỏ/reject" }
-oracle: "FE qua được nhưng BE phải chặn — test trực tiếp API bỏ qua FE."
+  - { id: CHK-SEC-IV-01, technique: "exceed boundary when the FE is bypassed (call the API directly)", expect: "the server rejects too" }
+  - { id: CHK-SEC-IV-02, technique: "wrong data type (string into a numeric field)", expect: "rejects with a valid error" }
+  - { id: CHK-SEC-IV-03, technique: "control/null bytes, control characters", expect: "stripped/rejected" }
+oracle: "The FE may pass but the BE must reject — test the API directly, bypassing the FE."

package/common/security/sqli.yaml

@@ -1,11 +1,11 @@
 # Security payload bank: SQL Injection — from common-checklist.xlsx (SQL Injection sheet).
 # Reusable adversarial values injected into the `invalid` group of any field via uses_security: [sqli].
 class: sqli
-description: SQL Injection — dữ liệu đầu vào nhằm phá câu truy vấn / bypass xác thực.
+description: SQL Injection — inputs crafted to break the query / bypass authentication.
 payloads:
-  - { id: CHK-SEC-SQLI-01, value: "admin' --", target: "login username", expect: "KHÔNG được đăng nhập bỏ qua mật khẩu" }
-  - { id: CHK-SEC-SQLI-02, value: "test' OR '1'='1", target: "ô tìm kiếm", expect: "KHÔNG trả về toàn bộ dữ liệu" }
-  - { id: CHK-SEC-SQLI-03, value: "test@test.com' OR '1'='1", target: "email đăng ký", expect: "xử lý hợp lệ, không lưu sai dữ liệu" }
-  - { id: CHK-SEC-SQLI-04, value: "test', isAdmin = 1 --", target: "sửa hồ sơ", expect: "KHÔNG nâng quyền trái phép" }
-  - { id: CHK-SEC-SQLI-05, value: "2023-01-01' OR '1'='1", target: "bộ lọc report", expect: "chỉ trả dữ liệu đúng filter" }
-oracle: "Bất kỳ dấu hiệu bypass/trả sai dữ liệu = lỗ hổng. Kỳ vọng: escape/parametrize an toàn, báo lỗi hợp lệ."
+  - { id: CHK-SEC-SQLI-01, value: "admin' --", target: "login username", expect: "must NOT log in bypassing the password" }
+  - { id: CHK-SEC-SQLI-02, value: "test' OR '1'='1", target: "search box", expect: "must NOT return all rows" }
+  - { id: CHK-SEC-SQLI-03, value: "test@test.com' OR '1'='1", target: "signup email", expect: "handled safely, no bad data stored" }
+  - { id: CHK-SEC-SQLI-04, value: "test', isAdmin = 1 --", target: "edit profile", expect: "must NOT escalate privileges" }
+  - { id: CHK-SEC-SQLI-05, value: "2023-01-01' OR '1'='1", target: "report filter", expect: "returns only the filtered data" }
+oracle: "Any sign of bypass / wrong data returned = a vulnerability. Expected: escape/parametrize safely, return a valid error."

package/common/security/upload.yaml

@@ -1,10 +1,10 @@
 # Security payload bank: Upload file — from common-checklist.xlsx (Upload file function).
 class: upload
-description: Upload file độc / vượt ràng buộc.
+description: Malicious / constraint-breaking file upload.
 payloads:
-  - { id: CHK-SEC-UP-01, technique: "file trá hình extension (shell.php.jpg)", expect: "kiểm tra MIME thật + whitelist, từ chối" }
-  - { id: CHK-SEC-UP-02, technique: "MIME mismatch (đổi Content-Type)", expect: "verify nội dung thật" }
-  - { id: CHK-SEC-UP-03, technique: "oversize vượt giới hạn", expect: "báo lỗi kích thước" }
-  - { id: CHK-SEC-UP-04, technique: "path traversal trong tên file (../../)", expect: "sanitize tên file, lưu đúng thư mục" }
-  - { id: CHK-SEC-UP-05, technique: "tên file chứa <script> / metadata độc", expect: "xử lý an toàn, không render ra DOM" }
-oracle: "Thực thi/ghi ngoài phạm vi = lỗ hổng."
+  - { id: CHK-SEC-UP-01, technique: "extension spoofing (shell.php.jpg)", expect: "checks real MIME + whitelist, rejects" }
+  - { id: CHK-SEC-UP-02, technique: "MIME mismatch (altered Content-Type)", expect: "verifies real content" }
+  - { id: CHK-SEC-UP-03, technique: "oversize beyond the limit", expect: "reports a size error" }
+  - { id: CHK-SEC-UP-04, technique: "path traversal in the filename (../../)", expect: "sanitizes the filename, stores in the right folder" }
+  - { id: CHK-SEC-UP-05, technique: "filename containing <script> / malicious metadata", expect: "handled safely, not rendered into the DOM" }
+oracle: "Execution / write outside scope = a vulnerability."

package/common/security/xss.yaml

@@ -1,12 +1,12 @@
 # Security payload bank: XSS Injection — from common-checklist.xlsx (XSS Injection sheet).
 class: xss
-description: Cross-Site Scripting — chèn script qua input/URL/attribute/file để thực thi trái phép.
+description: Cross-Site Scripting — inject script via input/URL/attribute/file to execute in the page.
 payloads:
-  - { id: CHK-SEC-XSS-01, value: "<script>alert('XSS')</script>", kind: "Reflected/Stored", expect: "hiển thị text thuần, KHÔNG thực thi script" }
-  - { id: CHK-SEC-XSS-02, value: "<img src=x onerror=alert(1)>", kind: "HTML attribute", expect: "không thực thi onerror" }
-  - { id: CHK-SEC-XSS-03, value: "<svg onload=alert(1)>", kind: "SVG payload", expect: "không thực thi onload / loại bỏ thuộc tính" }
-  - { id: CHK-SEC-XSS-04, value: "\"><script>alert(1)</script>", kind: "Attribute injection", expect: "không phá vỡ HTML, escape an toàn" }
-  - { id: CHK-SEC-XSS-05, value: "<a href=\"javascript:alert(1)\">click me</a>", kind: "Dangerous link", expect: "href bị vô hiệu / sanitize" }
-  - { id: CHK-SEC-XSS-06, value: "<script>alert(1)</script>.jpg", kind: "File name / metadata", expect: "tên file xử lý an toàn, không render ra DOM" }
-  - { id: CHK-SEC-XSS-07, value: "<h1>test</h1>", kind: "HTML injection", expect: "hiển thị dạng text, không render thẻ" }
-oracle: "Alert hiển thị / thẻ được render = lỗ hổng. Kỳ vọng: escape/sanitize, không innerHTML/eval user input."
+  - { id: CHK-SEC-XSS-01, value: "<script>alert('XSS')</script>", kind: "Reflected/Stored", expect: "renders as plain text, does NOT execute the script" }
+  - { id: CHK-SEC-XSS-02, value: "<img src=x onerror=alert(1)>", kind: "HTML attribute", expect: "does not fire onerror" }
+  - { id: CHK-SEC-XSS-03, value: "<svg onload=alert(1)>", kind: "SVG payload", expect: "does not fire onload / strips the attribute" }
+  - { id: CHK-SEC-XSS-04, value: "\"><script>alert(1)</script>", kind: "Attribute injection", expect: "does not break the HTML, escapes safely" }
+  - { id: CHK-SEC-XSS-05, value: "<a href=\"javascript:alert(1)\">click me</a>", kind: "Dangerous link", expect: "href disabled / sanitized" }
+  - { id: CHK-SEC-XSS-06, value: "<script>alert(1)</script>.jpg", kind: "File name / metadata", expect: "filename handled safely, not rendered into the DOM" }
+  - { id: CHK-SEC-XSS-07, value: "<h1>test</h1>", kind: "HTML injection", expect: "displayed as text, not rendered as a tag" }
+oracle: "An alert firing / a tag rendering = a vulnerability. Expected: escape/sanitize, no innerHTML/eval on user input."

package/common/techniques/boundary.yaml

@@ -1,6 +1,6 @@
-# Technique: Boundary Value Analysis — from phuong-phap §Nguồn-3.
+# Technique: Boundary Value Analysis — from the 4-source method.
 technique: boundary
-description: Khi field có min/max rõ ràng — sinh giá trị tại/quanh biên.
-rule: "Với [min,max]: sinh Min-1 (invalid), Min, Min+1, Max-1, Max, Max+1 (invalid)."
+description: When a field has a clear min/max — generate values at and around the boundary.
+rule: "For [min,max]: generate Min-1 (invalid), Min, Min+1, Max-1, Max, Max+1 (invalid)."
 applies_to: [number-integer, number-float, currency, string, password, phone, postcode]
-note: "Phải có 'đúng biên' (Min, Max), không chỉ 'quá biên' — off-by-one thường lọt ở đây."
+note: "Must include the exact boundary (Min, Max), not only over-boundary — off-by-one usually slips through here."

package/common/techniques/decision-table.yaml

@@ -1,6 +1,6 @@
-# Technique: Decision Table — from phuong-phap §Nguồn-3.
+# Technique: Decision Table — from the 4-source method.
 technique: decision-table
-description: Nhiều điều kiện kết hợp cùng ảnh hưởng 1 kết quả.
-rule: "Liệt kê tổ hợp điều kiện → hành động; sinh @cases theo mỗi rule row."
+description: Multiple combined conditions affecting one outcome.
+rule: "List condition combinations -> action; generate @cases from each rule row."
 applies_to: [login, permission, business-flow]
-example: "Login: mật khẩu đúng/sai × account khoá/không × 2FA bật/tắt."
+example: "Login: password correct/wrong x account locked/unlocked x 2FA on/off."

package/common/techniques/equivalence.yaml

@@ -1,6 +1,6 @@
-# Technique: Equivalence Partitioning — from phuong-phap §Nguồn-3.
+# Technique: Equivalence Partitioning — from the 4-source method.
 technique: equivalence
-description: Input chia thành nhóm cùng hành vi — chỉ cần 1 đại diện mỗi nhóm.
-rule: "Gom giá trị theo vùng tương đương (valid / mỗi loại invalid) → 1 đại diện/vùng, tránh test tràn lan."
+description: Inputs split into classes with the same behavior — one representative per class is enough.
+rule: "Group values into equivalence classes (valid / each kind of invalid) -> one representative per class, avoid over-testing."
 applies_to: [all]
-note: "Không cần 300 email sai — chỉ 1 đại diện cho mỗi CÁCH sai (thiếu @, sai vị trí ., full-width…)."
+note: "You don't need 300 bad emails — just one representative per WAY of being wrong (missing @, dot in wrong place, full-width...)."

package/common/techniques/state-transition.yaml

@@ -1,6 +1,6 @@
-# Technique: State Transition + Dependency State Coverage — from phuong-phap §Nguồn-3.
+# Technique: State Transition + Dependency State Coverage — from the 4-source method.
 technique: state-transition
-description: Đối tượng nhiều trạng thái; hoặc A phụ thuộc trạng thái của B.
-rule: "Phủ chuyển hợp lệ + chuyển NGƯỢC không hợp lệ; test X với B ở đủ trạng thái (active/chưa active/hết hạn/xoá mềm)."
+description: An object with multiple states; or A depends on the state of B.
+rule: "Cover valid transitions + INVALID reverse transitions; test X with B in every state (active/inactive/expired/soft-deleted)."
 applies_to: [workflow-entity, dependent-feature]
-example: "Draft → Submitted → Approved → Shipped (kể cả chuyển ngược không hợp lệ)."
+example: "Draft -> Submitted -> Approved -> Shipped (including invalid reverse transitions)."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-data-factory",
-  "version": "3.2.10-beta.13",
+  "version": "3.2.10-beta.15",
   "description": "Sungen Data Factory capability — standardized test-data generation from a field-type + security knowledge catalog (valid/boundary/invalid + traceability), the .overwrite merge layer, and (opt-in) @dataFactory runtime seeding. Design-time knowledge is runtime-free. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -14,7 +14,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.10-beta.13",
+    "@sun-asterisk/sungen": "3.2.10-beta.15",
     "yaml": "^2.4.0"
   },
   "files": [

package/src/catalog-loader.ts

@@ -101,8 +101,8 @@ export function loadEffectiveCatalog(projectDir: string, root = commonDir()): {
         if (!merged.security[bank]) {
           warnings.push({
             fieldType: type,
-            detail: `overwrite tham chiếu security bank "${bank}" không còn trong common`,
-            suggestion: `cập nhật hoặc xoá mục "${type}" trong qa/data-factory/common.overwrite.yaml`,
+            detail: `overwrite references security bank "${bank}" that no longer exists in the common catalog`,
+            suggestion: `update or remove the "${type}" entry in qa/data-factory/common.overwrite.yaml`,
           });
         }
       }

package/src/cli.ts

@@ -14,6 +14,7 @@ import { loadEffectiveCatalog } from './catalog-loader';
 import { expandFieldMap, renderTestData, type FieldMap } from './generator';
 import { lintFieldMap, summarize } from './lint';
 import { generateFixture } from './fixture';
+import { ensureDataFactoryReadme } from './readme';
 
 const FIELDMAP_DIR = (cwd: string) => join(cwd, 'qa', 'data-factory');
 const fieldMapPath = (cwd: string, name: string) => join(FIELDMAP_DIR(cwd), `${name}.fields.yaml`);
@@ -96,6 +97,7 @@ export function registerDataFactoryCommand(program: any): void {
     .option('--force', 'Overwrite existing test-data without asking (implies --yes)')
     .action(async (opts: { screen?: string; all?: boolean; yes?: boolean; force?: boolean }) => {
       const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
       if (opts.screen) { await genOne(cwd, opts.screen, opts); return; }
       if (!opts.all) {
         console.error('Specify --screen <name> for one unit, or --all for every unit (with confirmation).');
@@ -123,6 +125,7 @@ export function registerDataFactoryCommand(program: any): void {
     .option('--screen <name>', 'Lint one unit (default: all field-maps)')
     .action((opts: { screen?: string }) => {
       const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
       const names = opts.screen ? [opts.screen] : listFieldMaps(cwd);
       if (names.length === 0) { console.error('No field-maps under qa/data-factory/*.fields.yaml.'); process.exitCode = 1; return; }
       const { catalog } = loadEffectiveCatalog(cwd);
@@ -152,6 +155,7 @@ export function registerDataFactoryCommand(program: any): void {
     .option('--force', 'Overwrite existing fixture file(s) without asking')
     .action(async (opts: { screen: string; rows?: string; invalid?: boolean; force?: boolean }) => {
       const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
       const map = loadFieldMap(cwd, opts.screen);
       if (!map) { console.error(`✗ ${opts.screen}: no field-map at qa/data-factory/${opts.screen}.fields.yaml`); process.exitCode = 1; return; }
       const { catalog } = loadEffectiveCatalog(cwd);

package/src/generator.ts

@@ -94,14 +94,14 @@ function synthesize(dp: DataPoint, type: string, c: Record<string, any>): { valu
   if (dp.value != null) return { value: dp.value };
   const hint = `${dp.gen || ''} ${dp.note || ''}`.toLowerCase();
 
-  // Email length boundaries. `>` / "vượt" → over-boundary (invalid, offset +1).
+  // Email length boundaries. `>` / "over" → over-boundary (invalid, offset +1).
   if (type === 'email') {
-    const over = hint.includes('>') || hint.includes('vượt') || hint.includes('over');
+    const over = hint.includes('>') || hint.includes('over');
     const offset = over ? 1 : hint.includes('-1') ? -1 : hint.includes('+1') ? 1 : 0;
     if (hint.includes('maxlocal') || (hint.includes('local') && (hint.includes('max') || over))) {
       const v = synthEmail(c, 'maxLocal', offset); return v ? { value: v } : { value: null, todo: 'maxLocal' };
     }
-    if (hint.includes('maxtotal') || (hint.includes('tổng') && (hint.includes('max') || over)) || (hint.includes('total'))) {
+    if (hint.includes('maxtotal') || hint.includes('total')) {
       const v = synthEmail(c, 'maxTotal', offset); return v ? { value: v } : { value: null, todo: 'maxTotal' };
     }
   }

package/src/lint.ts

@@ -1,7 +1,7 @@
 /**
  * Data Factory lint — the deterministic coverage oracle from phuong-phap-tao-test-data.md §6.
  *
- * For each field it confirms the "đủ" checklist: ≥1 valid, boundary present when the field has a
+ * For each field it confirms the "is it enough" checklist: >=1 valid, boundary present when the field has a
  * length/number bound, ≥1 invalid per rule, no unresolved values, error codes mapped (not left as
  * placeholders). It also surfaces blind spots (type not in catalog) and — via the catalog loader —
  * stale `.overwrite` warnings. Pure functions; no side effects.

package/src/readme.ts

@@ -0,0 +1,52 @@
+/**
+ * Drops a `qa/data-factory/README.md` into the user's project so the folder explains itself.
+ * Write-if-absent (never clobbers a user-edited README), like a config file.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const README = `# \`qa/data-factory/\` — Data Factory (your project's test-data knowledge)
+
+This folder is your project's **test-data standard**: machine-readable data rules that
+\`sungen data gen\` / \`/sungen:create-data-test\` (and \`/sungen:create-test\` step 5.3) expand into
+standardized test-data — **valid / boundary / invalid** values, each carrying a \`CHK-*\` trace id back
+to the spec. It is a reusable asset that **survives \`sungen update\`** (only the driver's shipped
+catalog is refreshed; nothing here is touched).
+
+It is **not** a copy of your spec — it is the structured, reusable data-rules layer the deterministic
+generator needs, complementary to \`requirements/spec.md\` (which is prose spec per screen/flow).
+
+## What lives here
+
+| File | What it is |
+|---|---|
+| \`<name>.fields.yaml\` | **Field-map** for a screen/flow — one entry per input field: its catalog \`type\`, the project's real \`constraints\`, an \`errorMap\` (catalog placeholder code → your real message code), and optionally \`unique: true\`, nested \`fields:\`, \`dependsOn:\`. Authored from \`requirements/spec.md\`; expanded deterministically. A unit with **no input fields** (navigation/list) has no field-map — that's correct. |
+| \`common.overwrite.yaml\` | **Project-wide overrides** to the shipped catalog — your real length limits, real error codes, banned values, extra invalid cases. Deep-merged over the common (later-wins, keyed by \`type\` + data-point \`id\`). Genuinely new project knowledge the shipped catalog can't have. |
+| \`project/<entity>.yaml\` | **Blind-spot answers** — business enums, cross-entity rules, data models the catalog can't know. You fill these when Data Factory hits a field \`type\` it doesn't have (instead of it guessing). |
+| \`recipes.yaml\` | Seed recipes for the \`@dataFactory:<recipe>\` annotation — named field sets bound into \`{{recipe.*}}\` at runtime. |
+
+## Good to know
+
+- **\`sungen data gen\` merges** into \`test-data/<name>.yaml\` — it replaces only the field keys it owns
+  and preserves everything else (create-test data, flow-namespaced keys, \`@cases\`, overrides).
+- **\`unique: true\`** makes a field's valid value fresh per run (\`{{$timestamp}}\`) so a register
+  email/username never collides — no cross-run cache.
+- \`sungen data lint\` checks coverage; \`sungen data fixture\` builds a CSV import fixture under
+  \`qa/fixtures/\`.
+- Edit the field-map / \`.overwrite\` and re-run — never hand-edit the generated \`test-data\` values.
+
+Full guide: https://sungen.sun-asterisk.vn/docs/guides/data-factory
+`;
+
+/** Ensure `qa/data-factory/README.md` exists (write-if-absent). */
+export function ensureDataFactoryReadme(cwd: string): void {
+  const dir = join(cwd, 'qa', 'data-factory');
+  const path = join(dir, 'README.md');
+  if (existsSync(path)) return;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, README, 'utf8');
+  } catch {
+    /* best-effort — a missing README must never fail a data command */
+  }
+}

package/src/types.ts

@@ -9,7 +9,7 @@ export interface DataPoint {
   id: string;
   /** Literal value (present for concrete cases). */
   value?: string;
-  /** Human instruction to synthesize the value when it depends on project constraints (e.g. "local@ đúng maxLocal"). */
+  /** Human instruction to synthesize the value when it depends on project constraints (e.g. "local part = maxLocal"). */
   gen?: string;
   /** Why this value is invalid (invalid group only). */
   reason?: string;