@1aboveio/skills 0.0.0-stage → 1.0.1

package/skills/app-dev/better-auth/references/feishu-api.md

@@ -0,0 +1,270 @@
+# Feishu OAuth API Reference
+
+Load this file when implementing Feishu OAuth or troubleshooting auth issues.
+
+## OAuth Flow Endpoints
+
+### Authorization
+
+```
+GET https://accounts.feishu.cn/open-apis/authen/v1/authorize
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `client_id` | Yes | Feishu App ID (`cli_xxx`) |
+| `redirect_uri` | Yes | Must match registered URI exactly |
+| `response_type` | Yes | Always `code` |
+| `state` | Yes | CSRF token (managed by Better Auth) |
+| `scope` | No | Space-separated scopes |
+
+### Token Exchange
+
+```
+POST https://open.feishu.cn/open-apis/authen/v2/oauth/token
+Content-Type: application/json
+```
+
+**Request body:**
+```json
+{
+  "grant_type": "authorization_code",
+  "code": "<auth_code>",
+  "client_id": "cli_xxx",
+  "client_secret": "xxx"
+}
+```
+
+**Response:**
+```json
+{
+  "access_token": "u-xxxxxxxx",
+  "token_type": "Bearer",
+  "expires_in": 7200,
+  "refresh_token": "ur-xxxxxxxx",
+  "refresh_expires_in": 2592000
+}
+```
+
+> Note: v2 token endpoint returns flat JSON (no `data` wrapper). v1 used `data` wrapper.
+
+### User Info
+
+```
+GET https://open.feishu.cn/open-apis/authen/v1/user_info
+Authorization: Bearer <access_token>
+```
+
+**Response:**
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "open_id": "ou_xxxxxxxxxxxxxxxxxxxxxxxx",
+    "union_id": "on_xxxxxxxxxxxxxxxxxxxxxxxx",
+    "name": "张三",
+    "en_name": "John Zhang",
+    "email": "john@company.com",
+    "avatar_url": "https://internal-api-lark-file.feishu.cn/...",
+    "tenant_key": "xxxxxxxx",
+    "employee_no": ""
+  }
+}
+```
+
+> ⚠️ User data is nested under `data` — must unwrap once. Do NOT double-unwrap.
+
+### 1. Authorization (redirect user)
+
+```
+GET https://accounts.feishu.cn/open-apis/authen/v1/authorize
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `client_id` | Yes | Feishu App ID (`cli_xxx`) |
+| `redirect_uri` | Yes | Must match registered URI exactly |
+| `response_type` | Yes | Always `code` |
+| `state` | Yes | CSRF token (managed by Better Auth) |
+| `scope` | No | Space-separated scopes |
+
+### 2. Token Exchange
+
+```
+POST https://open.feishu.cn/open-apis/authen/v2/oauth/token
+Content-Type: application/json
+```
+
+**Request body:**
+```json
+{
+  "grant_type": "authorization_code",
+  "code": "<auth_code>",
+  "client_id": "cli_xxx",
+  "client_secret": "xxx"
+}
+```
+
+**Response:**
+```json
+{
+  "access_token": "u-xxxxxxxx",
+  "token_type": "Bearer",
+  "expires_in": 7200,
+  "refresh_token": "ur-xxxxxxxx",
+  "refresh_expires_in": 2592000
+}
+```
+
+> Note: v2 token endpoint returns flat JSON (no `data` wrapper). v1 used `data` wrapper.
+
+### 3. User Info
+
+```
+GET https://open.feishu.cn/open-apis/authen/v1/user_info
+Authorization: Bearer <access_token>
+```
+
+**Response:**
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "open_id": "ou_xxxxxxxxxxxxxxxxxxxxxxxx",
+    "union_id": "on_xxxxxxxxxxxxxxxxxxxxxxxx",
+    "name": "张三",
+    "en_name": "John Zhang",
+    "email": "john@company.com",
+    "avatar_url": "https://internal-api-lark-file.feishu.cn/...",
+    "tenant_key": "xxxxxxxx",
+    "employee_no": ""
+  }
+}
+```
+
+> ⚠️ User data is nested under `data` — must unwrap once. Do NOT double-unwrap.
+
+## User Info Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `open_id` | string | Unique per user per app — changes if app changes |
+| `union_id` | string | Unique per user across same developer's apps |
+| `name` | string | Display name (often Chinese) |
+| `en_name` | string | English name (may be empty) |
+| `email` | string | **Empty string if scope not approved** (not null, not omitted) |
+| `avatar_url` | string | Profile picture |
+| `tenant_key` | string | Organization identifier |
+| `employee_no` | string | Employee number (if configured) |
+
+## Scopes & Permissions
+
+| Scope | Level | Admin Approval |
+|-------|-------|----------------|
+| (none — basic profile) | Basic | Auto |
+| `contact:user.email:readonly` | Advanced (高级权限) | **Required** |
+| `contact:user.phone:readonly` | Advanced | **Required** |
+| `contact:user.employee_id:readonly` | Advanced | **Required** |
+
+### Activating Advanced Permissions
+
+1. Open app in [Feishu Dev Console](https://open.feishu.cn/app)
+2. Permissions → find the scope → **Enable**
+3. App Release → **Create Version** → **Submit for Review**
+4. Admin approves in Admin Console
+5. Permission status changes to **Active**
+
+Until approved: the field returns empty string `""`.
+
+## Error Codes
+
+| Code | Meaning | Fix |
+|------|---------|-----|
+| 0 | Success | — |
+| 10003 | Invalid app_id | Check credentials |
+| 10012 | App not released | Publish a version |
+| 10014 | Scope not approved | Request admin approval |
+| 20028 | Invalid code / expired | Code was reused or expired (10 min TTL) |
+| 20029 | Redirect URI mismatch | Add exact URL in Feishu app settings |
+
+## Prisma Schema
+
+Better Auth with genericOAuth requires these models:
+
+```prisma
+model User {
+  id            String    @id @default(cuid())
+  name          String?
+  email         String?   @unique
+  emailVerified Boolean   @default(false) @map("email_verified")
+  image         String?
+  createdAt     DateTime  @default(now()) @map("created_at")
+  updatedAt     DateTime  @updatedAt @map("updated_at")
+  sessions      Session[]
+  accounts      Account[]
+  @@map("users")
+}
+
+model Session {
+  id        String   @id @default(cuid())
+  expiresAt DateTime @map("expires_at")
+  token     String   @unique @default(cuid())
+  ipAddress String?  @map("ip_address")
+  userAgent String?  @map("user_agent")
+  userId    String   @map("user_id")
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+  @@map("sessions")
+}
+
+model Account {
+  id                    String    @id @default(cuid())
+  userId                String    @map("user_id")
+  accountId             String    @map("account_id")
+  providerId            String    @map("provider_id")
+  accessToken           String?   @map("access_token")
+  refreshToken          String?   @map("refresh_token")
+  idToken               String?   @map("id_token")
+  accessTokenExpiresAt  DateTime? @map("access_token_expires_at")
+  refreshTokenExpiresAt DateTime? @map("refresh_token_expires_at")
+  scope                 String?
+  password              String?
+  user                  User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+  createdAt             DateTime  @default(now()) @map("created_at")
+  updatedAt             DateTime  @updatedAt @map("updated_at")
+  @@unique([providerId, accountId])
+  @@map("accounts")
+}
+
+// Required by genericOAuth plugin for CSRF state
+model Verification {
+  id         String   @id @default(cuid())
+  identifier String
+  value      String
+  expiresAt  DateTime @map("expires_at")
+  createdAt  DateTime @default(now()) @map("created_at")
+  updatedAt  DateTime @updatedAt @map("updated_at")
+  @@map("verification")
+}
+```
+
+### Schema Gotchas
+
+- **`emailVerified` must be `Boolean`**, not `DateTime` — Better Auth writes `true`/`false`, not timestamps
+- **Account columns need `At` suffix** — `accessTokenExpiresAt` / `refreshTokenExpiresAt` (Prisma adapter uses camelCase field names)
+- **`@map()` for snake_case columns** — Prisma field names are camelCase; use `@map` for DB column names
+- **`verification` table is mandatory** — genericOAuth stores OAuth state here; missing table = 500 on sign-in
+
+## International (Lark) vs China (Feishu)
+
+| | China | International |
+|---|-------|---------------|
+| Base domain | `feishu.cn` | `larksuite.com` |
+| Auth URL | `accounts.feishu.cn` | `accounts.larksuite.com` |
+| API URL | `open.feishu.cn` | `open.larksuite.com` |
+| Dev Console | `open.feishu.cn/app` | `open.larksuite.com/app` |
+
+Use `FEISHU_BASE_URL` env var to switch between them.

package/skills/app-dev/better-auth/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/app-dev/data-catalog/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

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

@@ -0,0 +1,207 @@
+---
+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.38.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Data catalog
+
+Every output column of a warehouse table gets its definition written next to the
+code that computes it. A script turns those definitions into `docs/catalog/*.md`,
+and CI fails a pull request when the pages and the scripts disagree.
+
+## First use in a repo
+
+In a git repo with no `data-catalog.json`, set the repo up **before** the task you
+were asked to do, whatever it is: an audit, a new column, or a question. Setting up
+puts the engine, the CI check, and the conventions in the repo itself, so agents
+and people without this skill follow them from then on.
+
+1. `python3 <skill-base-dir>/scripts/data_catalog.py audit '<globs>'` to find the
+   table scripts; choose `--scripts` globs that cover them and nothing else.
+2. Pick `--languages` from the repo's existing docs (Chinese docs: `zh,en`;
+   otherwise `en`). Run `init` with them and `--write` ([Init](#init)).
+3. `node <skill-base-dir>/scripts/persist-conventions.mjs --repo-root <repo> --write`
+   writes the `## Data catalog conventions` section of `CONTRIBUTING.md` and points
+   `AGENTS.md` at it.
+4. Then do the task. In the reply, list what setup added, and say the Data catalog
+   check runs on PRs but is not required.
+
+Skip setup outside a git repo, or when the user says not to change the repo.
+Never document tables during setup unless the task asks for it.
+
+## Find your task
+
+| Task | Do |
+|---|---|
+| Writing or changing a table script | [While coding](#while-coding), then [references/field-definitions.md](references/field-definitions.md) |
+| "What does column X mean?" | Read `docs/catalog/<table>.md`; with no page, read the script's `CATALOG_FIELDS`, then its SQL |
+| The repo has no `data-catalog.json` | [First use in a repo](#first-use-in-a-repo) |
+| Find scripts with missing or weak definitions | [Audit](#audit) |
+| Document an existing table | [Backfill one table](#backfill-one-table) |
+| CI says the catalog is stale | `python3 <engine> generate`, commit the pages |
+| Before committing a table-script change, or reviewing one | `python3 <engine> drift` (`--base origin/main` for a whole branch) |
+| `Field`/`Table` arguments, the SQL block, config keys, exit codes | [references/format.md](references/format.md) |
+
+`<engine>` is `scripts/data-catalog/data_catalog.py` in the repo, or
+`<skill-base-dir>/scripts/data_catalog.py` before the repo has a copy. When
+`python3 <engine> version` differs from the skill's copy, refresh with
+`init --write`.
+
+## The files
+
+| File | Owner | Edit it? |
+|---|---|---|
+| `CATALOG_TABLE` / `CATALOG_FIELDS` in each `.py` table script | the definitions | yes |
+| `-- @table` / `-- @field` block at the top of each `.sql` table script | the definitions | yes |
+| `data-catalog.json` | which scripts, languages, output dir | yes, then rerun `init --write` |
+| `docs/catalog/*.md` | generated pages | never |
+| `catalog_fields.py` (path in `fieldsModule`) | generated `Field`/`Table` types | never |
+| `scripts/data-catalog/data_catalog.py` | engine copied from this skill | never; refresh with init |
+| `.github/workflows/data-catalog.yml` | generated CI check | never; rerun init |
+| `CONTRIBUTING.md` section between `conventions:data-catalog` markers | the conventions, for agents without this skill | never; rerun `persist-conventions.mjs --write`; the rest is yours |
+| `AGENTS.md` `## Contributing` pointer | points at `CONTRIBUTING.md` | written once by `persist-conventions.mjs` |
+
+## Rules
+
+1. **Define a column in the same change that creates or changes 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, 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).
+   Example: not `"Posted COLLECTION_IN rows where cust_type <> 'TEST', [dt-30d, dt), count distinct payer_bank via dim.forex join"`
+   but `"Number of different paying banks in the last 30 days. It is 0 if there were no collections."`
+3. **Write what the code does, read from the code.** Take the source table, filters,
+   and window from the SQL you read. When the code and the intended meaning
+   disagree, ask; never document the intent as fact.
+   Example: the SQL filters `status = 'POSTED'`, so the source says "posted
+   collections", even if the ticket said "all collections".
+4. **Edit the script, never a generated page.** `generate --check` fails while they
+   disagree, and when an output column has no definition: the contract tuple or, in
+   SQL, the SELECT writing the table, is checked against the `Field`s or `-- @field`s
+   ([references/format.md](references/format.md#what-ci-checks-against-the-code)).
+   Example: to fix a typo on a page, fix the `Field` text and run `generate`.
+5. **Derive the column contract only after every column has a `Field`.**
+   `PUBLISHED_COLUMNS = tuple(f.name for f in CATALOG_FIELDS)` publishes exactly the
+   documented columns, in `Field` order. Before switching, compare the derived tuple
+   with the old one: same names, same order.
+   Example: a 169-column table with 154 Fields would silently stop writing 15
+   columns. Keep the literal tuple; `generate` names the 15 until they are written.
+6. **Metadata is plain literals.** The engine reads the file without running it:
+   strings, implicit concatenation, `+`, module-level string constants, and
+   `*OTHER_FIELDS` from the same module. No f-strings, calls, or imported lists.
+   Example: share key columns with `KEYS = (Field(...),)` and `(*KEYS, Field(...))`
+   in the same file.
+7. **Audit reports; it never edits.** Fix one table per change, in the script that
+   builds the table, not its backfill or migration twins.
+8. **Adding the workflow adds a check, not a required one.** Make it required in
+   the merge rules only when the user asks.
+   Example: after `init --write`, report "the Data catalog check now runs on PRs
+   that touch table scripts; it is not required".
+
+## While coding
+
+1. Before changing a table script, read its page in `docs/catalog/`.
+2. Change the SQL or DataFrame code.
+3. Add, edit, or remove the matching `Field`. Write it with
+   [references/field-definitions.md](references/field-definitions.md).
+4. Run `python3 <engine> generate` and the repo's schema or contract tests.
+5. Run `python3 <engine> drift`. It lists columns whose code changed while their
+   definition did not, and filter or join changes with no definition touched. CI
+   only checks that every column has a definition; `drift` is the check that the
+   definitions still match the code. Update each listed definition, or say in the
+   PR why it still holds.
+6. Commit the script and the regenerated pages together.
+
+Example: changing `WHERE status = 'POSTED'` to `status IN ('POSTED', 'SETTLED')`
+passes CI, and `drift` reports "filters, joins or CTEs changed; no definition
+changed" until the affected sources say "posted or settled".
+
+A renamed column is a new `Field` and a removed one. Say in the new definition what
+it replaced when consumers must migrate.
+
+## Init
+
+```bash
+python3 <skill-base-dir>/scripts/data_catalog.py init \
+  --scripts 'dags/**/dwd_*.py' --scripts 'sql/**/*.sql' \
+  --exclude '**/*_legacy.py' --languages zh,en            # dry run: prints the plan
+python3 <skill-base-dir>/scripts/data_catalog.py init ... --write
+```
+
+Scope `--scripts` to warehouse table scripts. A broad `**/*.sql` also picks up app
+database migrations. `init` writes the config, the engine copy, `catalog_fields.py`
+beside the scripts, the workflow, and the first catalog. Rerunning is safe, and edits
+to `data-catalog.json` take effect on the next `init --write`. After a skill update,
+rerun both `init --write` and `persist-conventions.mjs --write` so the repo's copies
+match.
+
+The scripts import `from catalog_fields import Field, Table` at run time, so the
+module must ship with them like any sibling module (for example `--py-files` on
+`spark-submit`). Check that before merging.
+
+## Audit
+
+```bash
+python3 <engine> audit                          # scripts from data-catalog.json
+python3 <engine> audit 'dags/**/*.py' '**/*.sql' # before init
+python3 <engine> audit --json                   # for a worklist
+```
+
+The audit finds the table each script writes: `TARGET_TABLE`-style constants,
+`dst_db`/`dst_tbl`-style attributes, `saveAsTable`/`insertInto`, Hudi
+`hoodie.table.name`, and `INSERT`/`CREATE TABLE AS`/`MERGE` in SQL text. It reads
+output columns from a contract tuple (`PUBLISHED_COLUMNS`) or from the outermost
+SELECT. A repo with its own naming adds `--table-name NAME`/`--schema-name NAME`,
+or `tableNames`/`schemaNames` in the config.
+
+| Finding | Means | Fix |
+|---|---|---|
+| `no-catalog` | writes a table, carries no metadata | [Backfill](#backfill-one-table) in the builder script |
+| `undocumented` | output columns without a `Field` | write them |
+| `not-in-output` | `Field`s the SELECT no longer produces | remove or rename them |
+| `table-mismatch` | metadata names a table the script does not write | fix the name |
+| `contract-not-derived` | contract is a literal list next to complete metadata | derive it (rule 5) |
+| `relative-definition` | "same as above" text | write the row in full (rule 2) |
+| `repeated-text` | most rows share a phrase | move the shared fact to the table notes |
+| `code-in-description` | table names, operators or SQL functions in the meaning text | move lineage to `source` |
+| `long-definition` | over 30 words or 60 Chinese characters | cut to the column's own meaning |
+| `thin-definition` | text or source only restates the column name | say what it measures and where it comes from |
+| `columns-unknown` | DataFrame code the audit cannot read | compare the `Field`s with `DESCRIBE <table>` by hand |
+| `invalid-metadata` | the engine cannot read the metadata | the message names the line |
+
+Report the summary line and the findings for the tables in scope. Never claim a
+script is clean when its columns were `unknown`.
+
+## Backfill one table
+
+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 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.
+
+Uncertain rows: write what the code shows and list the open questions in the PR
+description for the user. Never leave a placeholder `Field`; `generate` refuses
+empty text.
+
+## Done when
+
+- `python3 <engine> generate --check` exits 0.
+- `python3 <engine> drift` exits 0, or you said in the PR why each listed definition
+  still holds.
+- `python3 <engine> audit` has no findings for the tables you touched, or you
+  reported the ones left and why.

package/skills/app-dev/data-catalog/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Data catalog"
+  short_description: "Column definitions in table scripts, a generated markdown catalog with a staleness CI check, and an audit of SQL and Spark scripts"

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

@@ -0,0 +1,76 @@
+## Data catalog conventions
+<!-- skill-script-path: consumer-copy -->
+
+Every output column of a warehouse table is defined in the script that builds the
+table. `docs/catalog/` is generated from those definitions; never edit it by hand.
+`data-catalog.json` lists the table scripts and the languages each definition carries.
+
+**Where definitions live**
+
+- 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
+  `-- @field column` per column, each followed by `--   key: value` lines
+  (`en:`, `zh:`, `source:`, `window:`, `unit:`).
+- Backfill and migration scripts that write the same table carry no definitions of
+  their own.
+
+**When you change a table script**
+
+1. Read the table's page in `docs/catalog/` first.
+2. Add, change, or remove the column's definition in the same change as the code.
+3. Run `python3 scripts/data-catalog/data_catalog.py generate`, and commit the script
+   and the regenerated pages together.
+4. Run `python3 scripts/data-catalog/data_catalog.py drift`. It lists columns whose
+   code changed while their definition did not. Update each, or say in the PR why
+   it still holds.
+
+**How to write a definition**
+
+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
+   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
+   time zone), and what 0 or null means when not obvious. No table names, joins, operators or
+   SQL functions there.
+3. Lead with the measure in one sentence: "Number of …", "Total …", "近 30 天…笔数".
+   Aim for 20 English words or 40 Chinese characters.
+4. `source` is lineage in one line: upstream `table.column`, the aggregation, and only
+   the filters this column adds. Example: "count distinct dwd.transaction.payer_bank".
+   Never copy the SQL into prose.
+5. Keep caveats that change how the value is used ("names compared as exact text");
+   leave out mechanics that don't.
+6. The exact interval goes in `window` and the unit code in `unit`; the text says
+   "last 7 days" and "USD".
+7. Every language says the same thing, written naturally in that language.
+8. Write sentences, not shorthand: keep the words that carry the logic (若…则, 当…时,
+   if, when, because). "若窗口内无收款，则为 0", not "无收款为 0"; "It is 0 if there were no
+   collections.", not "0 when none".
+9. Never restate the column name or write "same as above".
+10. Cover every case: what the column holds for each kind of row, including when it
+    is empty; list an enumerated column's values; say so if it is always empty today.
+11. Write related columns as a set: a count and its amount, a value and its missing
+    flag, a legacy column and its replacement use the same scope and wording, and any
+    difference is stated in both rows.
+
+Example row: `Field("payer_bank_cnt_30d", en="Number of different paying banks in the
+last 30 days. It is 0 if there were no collections.", zh="近 30 天不同付款银行数；若无收款，则为 0。", source="count
+distinct dwd.transaction.payer_bank", window="[dt-30d, dt)", unit="count")`
+
+**Contracts and CI**
+
+- A column contract (`PUBLISHED_COLUMNS`) is derived as
+  `tuple(f.name for f in CATALOG_FIELDS)` only once every column has a `Field`.
+  Before switching, check that the names and their order are unchanged.
+- The `Data catalog` workflow runs `generate --check` on PRs. It fails when a page is
+  stale, or when an output column has no definition. The column list comes from the
+  contract tuple or, in SQL, from the SELECT that writes the table. `drift` is not
+  run in CI.
+- `python3 scripts/data-catalog/data_catalog.py audit` lists scripts whose tables lack
+  definitions, and rows that break the writing rules (`repeated-text`,
+  `code-in-description`, `long-definition`, `thin-definition`, `relative-definition`).
+  It reports and never edits.