@1aboveio/skills 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1aboveio/skills",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Every 1aboveio skill package in one: install once, then choose which packages Pi loads with npx @1aboveio/skills select.",
   "license": "MIT",
   "repository": {
@@ -139,7 +139,7 @@
         ]
       }
     ],
-    "digest": "730da168eda4e3eedfb448db5dae6f8d0bc8c518bcb35a2c43e0b0acf538151e"
+    "digest": "0ff8c0fb72780cd0c50dfbeb86b50015c24ea65a76541075531b52e627d221a8"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skills/app-dev/airflow/SKILL.md

@@ -2,7 +2,7 @@
 name: airflow
 description: Airflow DAG architecture and conventions. Use when designing, writing, reviewing, testing, or debugging Airflow DAGs and tasks, including TaskGroups, data intervals, timezone-aware date parameters, CLI validation, environment-based scheduling, and pytest integrity tests.
 user-invocable: true
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Airflow DAG Development Patterns

package/skills/app-dev/android-foundation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: android-foundation
 description: "Prove an Expo / React Native app on a native Android emulator, and fix it when that proof fails. Use before you fix and re-run or re-dispatch a failed Android CI job (`gh workflow run android.yml`, `gh run rerun`): a re-run is not a debugger, so reproduce the failing journey checkpoint off CI first. Also use when a UiAutomator journey or its Python harness tests fail (a CHECK/FAIL line, a wait that timed out, a control not found, adb offline, a lost Metro bridge, a fixture failing on the runner), to build the debug APK and run the device journey, to set up a fresh Android workspace (SDK/NDK/JDK, Gradle caches, private AVD, disposable PostgreSQL), or to add the emulator job to CI. NOT for workflow YAML, CI speed or runner design (github-actions), browser tests (e2e-test), iOS (ios-foundation), plain Jest component tests, or signing and store release."
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Android foundation

package/skills/app-dev/app-debug/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: app-debug
 description: "Diagnose runtime failures in deployed Cloud Run services — 5xx/422 errors, tracebacks, Next.js SSR/hydration or Server Action failures, DB/Secret Manager connection errors, cold-start timeouts, container OOM. NOT for build or deploy failures (cloud-debug)."
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # App Debug

package/skills/app-dev/better-auth/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: better-auth
 description: "Add or debug Better Auth for Next.js App Router: login, sessions, protected routes, middleware, OAuth (including Feishu/Lark), cookies, Prisma, and Auth.js migration."
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Better Auth for Next.js

package/skills/app-dev/data-catalog/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: data-catalog
 description: "Column definitions for warehouse tables, written inside the Spark/PySpark or SQL script that builds each table (CATALOG_TABLE / CATALOG_FIELDS, or a `-- @field` comment block), with a generated markdown catalog in docs/catalog/ and a CI check that fails a PR whose catalog is stale. Use when writing or changing a table script that adds, renames, removes, or changes the meaning of an output column or feature; when asked what a warehouse column or feature means; to set a repo up ('init the data catalog', 'generate the data dictionary', '字段字典', 'add catalog CI'); or to audit existing SQL or Spark scripts for undocumented columns. NOT for implementing or tuning the Spark job itself (pyspark), DAG wiring (airflow), or general workflow YAML (github-actions)."
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Data catalog
@@ -68,7 +68,8 @@ Never document tables during setup unless the task asks for it.
    Example: adding `refund_cnt_30d` to the SELECT means adding its `Field` in the
    same commit, then running `generate`.
 2. **Each row says only what is particular to its column, in business words.**
-   Shared filters, window anchor and currency go once in the table notes; the row
+   Shared filters, window anchor and currency go once in the table notes, in every
+   language; the row
    gives what one value measures, its unit, and 0/null meaning; `source` gives
    lineage in one line. Follow the eleven principles in
    [references/field-definitions.md](references/field-definitions.md).
@@ -178,16 +179,18 @@ script is clean when its columns were `unknown`.
 
 ## Backfill one table
 
-1. Pick the script that builds the table from the audit. Its backfill, migrate, and
-   isolated twins share the definitions and need none of their own.
+1. Pick the script that builds the table from the audit. Backfill, migration, and
+   copy scripts that write the same table share its definitions and need none of
+   their own.
 2. Read the SQL or DataFrame code for every output column. Reuse an existing
    hand-written dictionary as a draft, and check every row against the code.
 3. Add `CATALOG_TABLE` and `CATALOG_FIELDS` in contract order. Keep the literal
    contract while you write.
 4. Run `generate` until it passes, then derive the contract and run the repo's
    schema tests (rule 5).
-5. Rerun the audit for that script, and fix `relative-definition` and
-   `thin-definition` findings.
+5. Rerun the audit for that script and fix its writing findings (`repeated-text`,
+   `code-in-description`, `long-definition`, `thin-definition`,
+   `relative-definition`), or leave one only when the text really belongs in that row.
 6. Commit the script and pages together. Replace the old hand-written dictionary
    with a link to the generated page.
 

package/skills/app-dev/data-catalog/references/data-catalog-conventions.md

@@ -7,7 +7,8 @@ table. `docs/catalog/` is generated from those definitions; never edit it by han
 
 **Where definitions live**
 
-- Python: `CATALOG_TABLE = Table("schema.table", grain=..., <language>=...)` and
+- Python: `CATALOG_TABLE = Table("schema.table", <language>=..., grain_<language>=...,
+  notes_<language>=(...))` (grain and notes in every language) and
   `CATALOG_FIELDS = (Field("column", <language>=..., source=..., window=..., unit=...), ...)`,
   imported `from catalog_fields import Field, Table`. Use plain string literals.
 - SQL: a comment block above the first statement: `-- @table schema.table`, then one
@@ -30,7 +31,7 @@ table. `docs/catalog/` is generated from those definitions; never edit it by han
 
 1. Say each fact once, at the widest level where it is true. Filters, the window
    anchor, currency, time zone, terms many columns use ("personal", "platform") and
-   list cleaning rules go in the table's `grain` or `notes`; a row says only what
+   list cleaning rules go in the table's grain or notes; a row says only what
    differs for that column.
 2. The description is meaning in business words: what one value measures, its unit
    and form (a ratio says 0–1 or percent; a time says date or timestamp and its

package/skills/app-dev/data-catalog/references/field-definitions.md

@@ -8,7 +8,7 @@ column that says only what is particular to that column.
 
 1. **Say each fact once, at the widest level where it is true.** A filter, window
    anchor, currency rule, or row-inclusion rule that holds for every column goes in
-   the table's `grain` or `notes`, never in each row. So does the meaning of a term
+   the table's grain or notes, never in each row. So does the meaning of a term
    many columns use ("personal", "platform", "own name") and how lists are cleaned
    (case, sorting, empty items). A row carries only what differs for that column.
    Bad (every row): `"Posted collections only, test customers excluded, [dt-7d, dt), excluding dt; ..."`
@@ -66,10 +66,10 @@ column that says only what is particular to that column.
 
 | Fact | Goes in |
 |---|---|
-| What one row is, which rows exist | `Table.grain` |
+| What one row is, which rows exist | `Table` `grain_<lang>` |
 | What the table is for, its main source | `Table` language text |
-| Filters, window anchor, currency, time zone shared by all columns | `Table.notes` |
-| Meaning of a term many columns use, list cleaning rules | `Table.notes` |
+| Filters, window anchor, currency, time zone shared by all columns | `Table` `notes_<lang>` |
+| Meaning of a term many columns use, list cleaning rules | `Table` `notes_<lang>` |
 | What this column measures, its unit in words, 0/null meaning | `Field` language text |
 | Upstream column, aggregation, filters only this column adds | `Field.source` |
 | Exact interval / unit code | `Field.window` / `Field.unit` |
@@ -81,15 +81,22 @@ Table:
 ```python
 CATALOG_TABLE = Table(
     "dwd.customer_daily",
-    grain="One row per (dt, cust_id) for each customer with a posted collection before dt.",
     en="Daily customer collection metrics for risk features.",
     zh="客户每日收款指标，供风险特征使用。",
-    notes=(
+    grain_en="One row per (dt, cust_id) for each customer with a posted collection before dt.",
+    grain_zh="每个 (dt, cust_id) 一行；只有 dt 之前有已入账收款的客户才有行。",
+    notes_en=(
         "All metrics count posted collections (status 'POSTED') from non-test customers.",
         "Windows end the day before dt: 'last 7 days' is [dt-7d, dt).",
         "Amounts are converted to USD at the transaction date's rate; collections with no rate are left out of every metric.",
         "Every metric is 0, not empty, if the customer had no collections in its window.",
     ),
+    notes_zh=(
+        "所有指标只计非测试客户的已入账（status 为 'POSTED'）收款。",
+        "窗口截至 dt 前一天：「近 7 天」指 [dt-7d, dt)，含 dt-7d，不含 dt。",
+        "金额按交易日汇率换算为美元；若某笔收款当天没有汇率，则所有指标都不计这笔收款。",
+        "若客户在窗口内没有收款，则指标为 0，而不是空值。",
+    ),
 )
 ```
 

package/skills/app-dev/data-catalog/references/format.md

@@ -7,13 +7,18 @@ from catalog_fields import Field, Table
 
 CATALOG_TABLE = Table(
     "dwd.customer_daily",
-    grain="One row per (dt, cust_id) for each customer with a posted transaction that day.",
     en="Daily customer collection rollup used by risk features.",
     zh="客户每日收款汇总，供风险特征使用。",
-    notes=(
+    grain_en="One row per (dt, cust_id) for each customer with a posted transaction that day.",
+    grain_zh="每个 (dt, cust_id) 一行；只有当天有已入账交易的客户才有行。",
+    notes_en=(
         "All metrics count posted collections (status 'POSTED').",
         "Amounts are converted to USD at the transaction date's rate.",
     ),
+    notes_zh=(
+        "所有指标只计已入账（status 为 'POSTED'）的收款。",
+        "金额按交易日汇率换算为美元。",
+    ),
 )
 
 KEYS = (
@@ -37,7 +42,9 @@ PUBLISHED_COLUMNS = tuple(f.name for f in CATALOG_FIELDS)
 ```
 
 - `Field(name, <one keyword per language>, source, window=None, unit=None)`.
-- `Table(name, grain, <one keyword per language>, notes=())`.
+- `Table(name, <one keyword per language>, grain_<lang>=..., notes_<lang>=(...))`: a
+  grain for every language, and the same number of notes in every language (notes are
+  optional).
 - Pass only the name positionally; everything else by keyword.
 - The language keywords come from `languages` in `data-catalog.json`. `init`
   regenerates `catalog_fields.py` with exactly those, so a missing language is a
@@ -49,10 +56,12 @@ PUBLISHED_COLUMNS = tuple(f.name for f in CATALOG_FIELDS)
 
 ```sql
 -- @table ads.merchant_monthly
---   grain: One row per (month, merchant_id).
+--   grain_en: One row per (month, merchant_id).
+--   grain_zh: 每个 (month, merchant_id) 一行。
 --   en: Monthly settled volume per merchant.
 --   zh: 商户月度结算金额。
---   notes: Built on the 1st of each month; Counts settled rows (status 'SETTLED') only; Excludes test merchants
+--   notes_en: Built on the 1st of each month; Counts settled rows (status 'SETTLED') only; Excludes test merchants
+--   notes_zh: 每月 1 日构建；只计已结算（status 为 'SETTLED'）的记录；不含测试商户
 -- @field merchant_id
 --   en: Merchant that settled the volume; key of dim_merchant.
 --   zh: 结算该金额的商户，dim_merchant 主键。
@@ -70,7 +79,7 @@ SELECT ...
 - A directive line is `-- @table <name>` or `-- @field <name>`.
 - A key line is exactly two spaces after `-- `, then `key: value`.
 - A continuation line has four or more spaces and joins the previous key with a space.
-- `notes` on `@table` splits on `;`.
+- `notes_<lang>` on `@table` splits on `;` or `；`.
 - The block ends at the first non-comment line. One `@table` per file.
 
 ## data-catalog.json

package/skills/app-dev/data-catalog/scripts/data_catalog.py

@@ -157,9 +157,9 @@ class FieldDoc:
 class TableDoc:
     name: str
     script: str
-    grain: str
+    grain: dict   # language -> what one row is
     text: dict
-    notes: list
+    notes: dict   # language -> [shared rules]
     fields: list
     line: int
     contracts: dict = field(default_factory=dict)  # name -> list[str] | "derived" | "unchecked"
@@ -263,21 +263,54 @@ def build_field(values: dict, languages: list, where: str, line: int) -> FieldDo
 
 def build_table(values: dict, fields: list, languages: list, where: str, line: int, script: str) -> TableDoc:
     name = require_text(values, "name", where, line, "Table")
-    known = {"name", "grain", "notes", *languages}
+    if "grain" in values or "notes" in values:
+        keys = ", ".join(f"grain_{lang}=..., notes_{lang}=(...)" for lang in languages)
+        raise CatalogError(f"{where}:{line}: Table {name!r}: grain and notes are written per language: {keys}")
+    known = {"name", *languages, *(f"grain_{lang}" for lang in languages), *(f"notes_{lang}" for lang in languages)}
     unknown = sorted(set(values) - known)
     if unknown:
         raise CatalogError(f"{where}:{line}: Table {name!r} has unknown argument(s) {unknown}")
-    grain = require_text(values, "grain", where, line, f"Table {name!r}")
     text = {lang: require_text(values, lang, where, line, f"Table {name!r}") for lang in languages}
-    notes = values.get("notes") or ()
-    if isinstance(notes, str):
-        notes = (notes,)
-    return TableDoc(name, script, grain, text, [n.strip() for n in notes if n and n.strip()], fields, line)
+    grain = {lang: require_text(values, f"grain_{lang}", where, line, f"Table {name!r}") for lang in languages}
+    notes = {}
+    for lang in languages:
+        raw = values.get(f"notes_{lang}") or ()
+        raw = (raw,) if isinstance(raw, str) else raw
+        notes[lang] = [n.strip() for n in raw if n and n.strip()]
+    counts = {lang: len(n) for lang, n in notes.items()}
+    if len(set(counts.values())) > 1:
+        raise CatalogError(f"{where}:{line}: Table {name!r}: every language needs the same notes, got {counts}")
+    return TableDoc(name, script, grain, text, notes, fields, line)
+
+
+def struct_fields(node: ast.AST, names: dict):
+    """Column names of a literal StructType([StructField("name", ...), ...]), or None."""
+    if call_name(node) != "StructType" or not node.args:
+        return None
+    try:
+        items = resolve_sequence(node.args[0], names, "", frozenset())
+    except CatalogError:
+        return None
+    out = []
+    for item in items:
+        if call_name(item) != "StructField" or not item.args:
+            return None
+        try:
+            value = eval_text(item.args[0], names, "")
+        except CatalogError:
+            return None
+        if not isinstance(value, str):
+            return None
+        out.append(value)
+    return out
 
 
 def contract_state(node: ast.AST, names: dict):
     if any(isinstance(n, ast.Name) and n.id == FIELDS_VAR for n in ast.walk(node)):
         return "derived"
+    columns = struct_fields(node, names)
+    if columns is not None:
+        return columns
     try:
         items = resolve_sequence(node, names, "", frozenset())
         values = [eval_text(item, names, "") for item in items]
@@ -363,14 +396,12 @@ def parse_sql(text: str, where: str, languages: list) -> TableDoc | None:
     fields = []
     for kind, name, values, line, _ in entries:
         if kind == "field":
-            if "notes" in values:
-                raise CatalogError(f"{where}:{line}: `notes` belongs on @table, not @field")
+            if any(k.startswith(("notes", "grain")) for k in values):
+                raise CatalogError(f"{where}:{line}: `grain_*` and `notes_*` belong on @table, not @field")
             fields.append(build_field({"name": name, **values}, languages, where, line))
     _, name, values, line, _ = tables[0]
-    notes = values.pop("notes", None)
-    values = {"name": name, **values}
-    if notes:
-        values["notes"] = tuple(n.strip() for n in notes.split(";"))
+    values = {"name": name, **{k: tuple(n.strip() for n in re.split(r"[;；]", v)) if k.startswith("notes_") else v
+                               for k, v in values.items()}}
     return build_table(values, fields, languages, where, line, where)
 
 
@@ -467,6 +498,9 @@ def cell(text: str | None) -> str:
     return text.replace("\\", "\\\\").replace("|", "\\|").replace("\r\n", "\n").replace("\n", "<br>")
 
 
+SECTION_LABELS = {"en": ("Grain:", "Notes:"), "zh": ("粒度：", "说明："), "zh_hant": ("粒度：", "說明：")}
+
+
 def label(lang: str) -> str:
     return LANGUAGE_LABELS.get(lang, lang)
 
@@ -496,17 +530,19 @@ def render_table(table: TableDoc, root: Path, config: dict) -> str:
     langs = config["languages"]
     out = [GENERATED_MARK, "", f"# `{table.name}`", ""]
     out.append(f"- **Script:** [{table.script}]({link_to(root, config['output'], table.script)})")
-    out.append(f"- **Grain:** {cell(table.grain)}")
     out.append(f"- **Fields:** {len(table.fields)}")
     out.append("")
     for lang in langs:
-        out.append(f"**{label(lang)}:** {cell(table.text[lang])}" if len(langs) > 1 else cell(table.text[lang]))
-        out.append("")
-    if table.notes:
-        out.append("**Notes:**")
-        out.append("")
-        out.extend(f"- {cell(note)}" for note in table.notes)
+        grain_label, notes_label = SECTION_LABELS.get(lang, SECTION_LABELS["en"])
+        if len(langs) > 1:
+            out += [f"## {label(lang)}", ""]
+        out += [cell(table.text[lang]), "", f"- **{grain_label}** {cell(table.grain[lang])}"]
+        if table.notes[lang]:
+            out.append(f"- **{notes_label}**")
+            out.extend(f"  - {cell(note)}" for note in table.notes[lang])
         out.append("")
+    if len(langs) > 1:
+        out += ["## Fields", ""]
     has_window = any(f.window for f in table.fields)
     has_unit = any(f.unit for f in table.fields)
     head = ["Field", *(label(lang) for lang in langs), "Source"]
@@ -539,7 +575,7 @@ def render_index(tables: list, root: Path, config: dict) -> str:
     out += ["| Table | Summary | Grain | Fields | Script |", "|---|---|---|---|---|"]
     for t in tables:
         script = f"[{t.script}]({link_to(root, config['output'], t.script)})"
-        out.append(f"| [`{t.name}`]({page_name(t)}) | {cell(t.text[lang])} | {cell(t.grain)} | {len(t.fields)} | {script} |")
+        out.append(f"| [`{t.name}`]({page_name(t)}) | {cell(t.text[lang])} | {cell(t.grain[lang])} | {len(t.fields)} | {script} |")
     return "\n".join(out) + "\n"
 
 
@@ -1019,11 +1055,13 @@ def preview(items: list, limit: int = 12) -> str:
     return shown + (f", … (+{len(items) - limit})" if len(items) > limit else "")
 
 
-def cmd_audit(root: Path, globs: list, as_json: bool, verbose: bool, table_names: list, schema_names: list) -> int:
+def cmd_audit(root: Path, globs: list, as_json: bool, verbose: bool, table_names: list, schema_names: list,
+              contracts: list) -> int:
     config_path = root / CONFIG_FILE
     config = load_config(root) if config_path.exists() else dict(DEFAULT_CONFIG)
     config = {**config, "tableNames": [*config["tableNames"], *table_names],
-              "schemaNames": [*config["schemaNames"], *schema_names]}
+              "schemaNames": [*config["schemaNames"], *schema_names],
+              "contracts": [*config["contracts"], *contracts]}
     if globs:
         patterns, exclude = globs, config.get("exclude", [])
     elif config_path.exists():
@@ -1138,7 +1176,8 @@ def definitions(table: TableDoc | None) -> tuple[dict, tuple]:
     if table is None:
         return {}, ()
     fields = {f.name: (tuple(sorted(f.text.items())), f.source, f.window, f.unit) for f in table.fields}
-    return fields, (table.grain, tuple(sorted(table.text.items())), tuple(table.notes))
+    notes = tuple((lang, tuple(n)) for lang, n in sorted(table.notes.items()))
+    return fields, (tuple(sorted(table.grain.items())), tuple(sorted(table.text.items())), notes)
 
 
 def drift_items(root: Path, config: dict, base: str) -> list:
@@ -1212,12 +1251,14 @@ def cmd_drift(root: Path, base: str) -> int:
 
 def render_fields_module(languages: list) -> str:
     lang_fields = "\n".join(f"    {lang}: str" for lang in languages)
+    grain_fields = "\n".join(f"    grain_{lang}: str" for lang in languages)
+    notes_fields = "\n".join(f"    notes_{lang}: tuple[str, ...] = ()" for lang in languages)
     return f'''"""Column metadata types for the data catalog.
 
 Generated by data_catalog.py init from data-catalog.json; rerun init after changing
 `languages` there, never edit this file. Table scripts declare:
 
-    CATALOG_TABLE = Table("schema.table", grain=..., {", ".join(f"{lang}=..." for lang in languages)})
+    CATALOG_TABLE = Table("schema.table", {", ".join(f"{lang}=..., grain_{lang}=..." for lang in languages)})
     {FIELDS_VAR} = (Field("column", {", ".join(f"{lang}=..." for lang in languages)}, source=...), ...)
     PUBLISHED_COLUMNS = tuple(f.name for f in {FIELDS_VAR})
 """
@@ -1238,9 +1279,9 @@ class Field:
 @dataclass(frozen=True)
 class Table:
     name: str
-    grain: str
 {lang_fields}
-    notes: tuple[str, ...] = ()
+{grain_fields}
+{notes_fields}
 '''
 
 
@@ -1367,6 +1408,8 @@ def main(argv: list | None = None) -> int:
                          help="extra variable/attribute whose string value is the table written; repeatable")
     p_audit.add_argument("--schema-name", action="append", default=[], metavar="NAME",
                          help="extra variable/attribute holding that table's schema; repeatable")
+    p_audit.add_argument("--contract", action="append", default=[], metavar="NAME",
+                         help="extra column-contract name (tuple of names or StructType); repeatable")
     p_drift = sub.add_parser("drift", help="local check: code changed since a git base while its definitions did not")
     p_drift.add_argument("--base", default="HEAD", help="git ref to compare with (default HEAD: uncommitted work)")
     sub.add_parser("version", help="print the engine identity")
@@ -1382,7 +1425,7 @@ def main(argv: list | None = None) -> int:
             return cmd_generate(root, args.check)
         if args.command == "drift":
             return cmd_drift(root, args.base)
-        return cmd_audit(root, args.globs, args.json, args.verbose, args.table_name, args.schema_name)
+        return cmd_audit(root, args.globs, args.json, args.verbose, args.table_name, args.schema_name, args.contract)
     except CatalogError as exc:
         print(f"data-catalog: {exc}", file=sys.stderr)
         return 2

package/skills/app-dev/data-catalog/scripts/test_data_catalog.py

@@ -25,10 +25,12 @@ WINDOW_NOTE = "[dt-7d, dt)"
 
 CATALOG_TABLE = Table(
     "dwd.customer_daily",
-    grain="one row per (dt, cust_id)",
     en="Daily customer collection rollup.",
     zh="客户每日收款汇总。",
-    notes=("Amounts in USD via dim_forex.",),
+    grain_en="one row per (dt, cust_id)",
+    grain_zh="每个 (dt, cust_id) 一行",
+    notes_en=("Amounts in USD via dim_forex.",),
+    notes_zh=("金额经 dim_forex 换算为 USD。",),
 )
 KEYS = (
     Field("dt", en="Snapshot date.", zh="快照日期。", source="Run parameter `dt`."),
@@ -50,10 +52,12 @@ PUBLISHED_COLUMNS = tuple(f.name for f in CATALOG_FIELDS)
 
 SQL_SCRIPT = """\
 -- @table ads.merchant_monthly
---   grain: one row per (month, merchant_id)
 --   en: Monthly merchant volume.
 --   zh: 商户月度交易量。
---   notes: Built monthly; Excludes test merchants
+--   grain_en: one row per (month, merchant_id)
+--   grain_zh: 每个 (month, merchant_id) 一行
+--   notes_en: Built monthly; Excludes test merchants
+--   notes_zh: 每月构建；不含测试商户
 -- @field merchant_id
 --   en: Merchant id.
 --   zh: 商户 ID。
@@ -111,7 +115,10 @@ class GenerateTest(unittest.TestCase):
         self.assertIn("| `volume_usd` | Settled volume in the month. | 当月结算金额。 | "
                       "dwd_settlement settled rows, summed amount_usd | USD |", sql_page)
         self.assertNotIn("Window", sql_page)
-        self.assertIn("- Excludes test merchants", sql_page)
+        self.assertIn("  - Excludes test merchants", sql_page)
+        self.assertIn("## 中文", sql_page)
+        self.assertIn("- **粒度：** 每个 (month, merchant_id) 一行", sql_page)
+        self.assertIn("  - 不含测试商户", sql_page)
         index = (root / "docs/catalog/README.md").read_text(encoding="utf-8")
         self.assertLess(index.index("ads.merchant_monthly"), index.index("dwd.customer_daily"))
         self.assertIn("| [`dwd.customer_daily`](dwd.customer_daily.md) | Daily customer collection rollup. | "
@@ -192,6 +199,18 @@ SELECT dt, SUM(amt) AS coll_amt_7d_usd, COUNT(*) AS coll_cnt_7d FROM dwd.txn GRO
         root = make_repo({"jobs/a.py": imported}, BILINGUAL)
         self.assertIn("imported lists cannot be read", run(root, "generate")[2])
 
+    def test_table_grain_and_notes_are_per_language_with_matching_notes(self):
+        old = PY_SCRIPT.replace('grain_en="one row per (dt, cust_id)",', 'grain="one row per (dt, cust_id)",')
+        root = make_repo({"jobs/a.py": old}, BILINGUAL)
+        code, _, err = run(root, "generate")
+        self.assertEqual(code, 1)
+        self.assertIn("grain and notes are written per language: grain_en=..., notes_en=(...), grain_zh=...", err)
+        uneven = PY_SCRIPT.replace('notes_zh=("金额经 dim_forex 换算为 USD。",),', 'notes_zh=(),')
+        root = make_repo({"jobs/a.py": uneven}, BILINGUAL)
+        code, _, err = run(root, "generate")
+        self.assertEqual(code, 1)
+        self.assertIn("every language needs the same notes, got {'en': 1, 'zh': 0}", err)
+
     def test_same_table_in_two_scripts_is_an_error(self):
         root = make_repo({"jobs/a.py": PY_SCRIPT, "jobs/b.py": PY_SCRIPT}, BILINGUAL)
         code, _, err = run(root, "generate")
@@ -238,6 +257,18 @@ class AuditTest(unittest.TestCase):
                          "writes dwd.undocumented but carries no CATALOG_TABLE/CATALOG_FIELDS (or -- @table block); "
                          "also written by jobs/backfill_b.py (put the metadata in the script that builds the table)")
 
+    def test_a_structtype_contract_is_read_for_its_column_names(self):
+        script = '''
+        L1A_PUBLISHED_SCHEMA = StructType([
+            StructField("dt", DateType(), False),
+            StructField("cust_id", StringType(), False),
+        ])
+        TARGET_TABLE = "dwd.flow"
+        '''
+        root = make_repo({"jobs/flow.py": script})
+        [entry] = json.loads(run(root, "audit", "--json", "--contract", "L1A_PUBLISHED_SCHEMA", "jobs/*.py")[1])["scripts"]
+        self.assertEqual((entry["columns"], entry["columnsFrom"]), (["dt", "cust_id"], "L1A_PUBLISHED_SCHEMA"))
+
     def test_class_attributes_name_the_table_with_their_schema(self):
         script = '''
         class OrdersEtl(Etl):
@@ -311,7 +342,7 @@ class AuditTest(unittest.TestCase):
                 ("c_amt", " ".join(["word"] * 31), "近 7 天收款总额。", "sum of amount"),
             ])
         script = f'''
-CATALOG_TABLE = Table("dwd.t", grain="One row per id.", en="Table.", zh="表。")
+CATALOG_TABLE = Table("dwd.t", en="Table.", zh="表。", grain_en="One row per id.", grain_zh="每个 id 一行。")
 CATALOG_FIELDS = (
 {rows}
 )
@@ -329,8 +360,9 @@ CATALOG_FIELDS = (
 
     def test_shared_vocabulary_and_plain_units_are_not_flagged(self):
         script = '''
-CATALOG_TABLE = Table("dwd.t", grain="One row per id.", en="Table.", zh="表。",
-                      notes=("All metrics count posted collections.", "Every metric is 0 if there were no collections."))
+CATALOG_TABLE = Table("dwd.t", en="Table.", zh="表。", grain_en="One row per id.", grain_zh="每个 id 一行。",
+                      notes_en=("All metrics count posted collections.", "Every metric is 0 if there were no collections."),
+                      notes_zh=("所有指标只计已入账收款。", "若窗口内无收款，则指标为 0。"))
 CATALOG_FIELDS = (
     Field("a", en="Number of collections in the last 7 days.", zh="近 7 天收款笔数。",
           source="count of dwd.transaction rows", window="[dt-7d, dt)"),
@@ -390,9 +422,9 @@ class ReviewFixTest(unittest.TestCase):
         self.assertIn("no column contract and no readable SELECT writing ads.merchant_monthly", err)
 
     def test_tables_mapping_to_one_page_or_the_index_are_errors(self):
-        a = PY_SCRIPT.replace('"dwd.customer_daily",\n    grain', '"ads.a_b",\n    grain')
-        b = PY_SCRIPT.replace('"dwd.customer_daily",\n    grain', '"ads.a b",\n    grain')
-        readme = PY_SCRIPT.replace('"dwd.customer_daily",\n    grain', '"README",\n    grain')
+        a = PY_SCRIPT.replace('"dwd.customer_daily",\n    en=', '"ads.a_b",\n    en=')
+        b = PY_SCRIPT.replace('"dwd.customer_daily",\n    en=', '"ads.a b",\n    en=')
+        readme = PY_SCRIPT.replace('"dwd.customer_daily",\n    en=', '"README",\n    en=')
         root = make_repo({"jobs/a.py": a, "jobs/b.py": b, "jobs/c.py": readme}, BILINGUAL)
         code, _, err = run(root, "generate")
         self.assertEqual(code, 1)

package/skills/app-dev/ios-foundation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ios-foundation
 description: "Set up and prove an Expo / React Native native iOS workspace from a clean checkout to a manual Login smoke on an owned iOS Simulator: isolated worktree and private caches, Xcode/runtime/CocoaPods preflight, frozen install with `pod install --deployment`, platform-scoped prebuild, an ad-hoc-signed Debug simulator build, a private simulator by exact UDID, Metro on a free port, a disposable PostgreSQL backend with owned cleanup, and the evidence record (setup proof only; feature work reports the smoke result). Use for 'set up iOS', 'build the iOS app', 'run the app on the iOS simulator', 'add iOS to the React Native app', 'prove the iOS build', or when a pod install, xcodebuild, simulator boot, Metro connection or Keychain session fails. NOT for Android (android-foundation), signing, TestFlight or App Store release, or general workflow YAML (github-actions)."
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # iOS foundation

package/skills/app-dev/monorepo/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: monorepo
 description: Turborepo architecture for shared packages, pnpm workspaces, DAL boundaries, and pipelines.
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Turborepo Monorepo Architecture

package/skills/app-dev/nextjs-fullstack/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: nextjs-fullstack
 description: "Build or debug Next.js App Router features with React 19 — pages/layouts/route handlers, Server/Client Components, Server Actions, forms, middleware, DAL, strict TypeScript, Zod — plus our conventions: nuqs URL state, SWR cache, Skeleton/Progress + Sonner feedback, drag-and-drop upload, the portal app shell, list pages as filter/sort/paginate tables. shadcn component mechanics: see the shadcn skill."
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Next.js 16 Fullstack Development

package/skills/app-dev/prisma-setup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: prisma-setup
 description: Use when adding or debugging Prisma with PostgreSQL, Next.js, or Turborepo, including schema.prisma, prisma.config.ts, client generation, migrations, seeds, relations, adapters, and DAL/database-layer setup. Triggers on phrases like "Prisma schema", "prisma migrate", "schema.prisma", "seed the database", "PrismaClient error", "relation issue", or "database layer".
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Prisma v7 Setup Guide

package/skills/app-dev/pyspark/SKILL.md

@@ -12,7 +12,7 @@ description: >
   Connect, spark-submit, Hudi commits, backfills, validate-only canaries,
   cluster reconciliation, or Spark event-log profiling — including warehouse
   job timeouts, empty Hudi writes, or EMR/Dataproc performance regressions.
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # PySpark

package/skills/app-dev/python-backend/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: python-backend
 description: "Python backend architecture for FastAPI, Tortoise ORM, Pydantic Settings, loguru, and uv. Also: uv.lock installs in CI/Docker via a proxy or mirror (`uv sync --frozen` bypasses it), slow uv installs on runners, relocking."
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Python Backend Conventions

package/skills/app-dev/shadcn/SKILL.md

@@ -2,7 +2,7 @@
 name: shadcn
 description: "Add or debug shadcn/ui in a React/Next.js project: components.json, shadcn init/add, presets, registries, Tailwind styling, base/radix/aria composition, component fixes, and list-index pages — where the default is the DiceUI data table with filter/sort/pagination in the URL via nuqs, not a bare shadcn Table."
 allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # shadcn/ui

package/skills/app-dev/zod-v4/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: zod-v4
 description: Zod v4 schema conventions and v3 migration for errors, validators, objects, enums, records, and async parsing.
-release-version: 0.36.0
+release-version: 0.38.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Zod v3 to v4 Migration