docs: auto-generate schema docs and remove from README.md

It was a huge time sink manually maintaining the schema tables
in README.md, and resolving resulting merge conflicts.  So instead
auto-generate these into SCHEMAS.md.

Author: aspiers

.changeset/move-schema-docs-to-autogenerated-file.md

@@ -0,0 +1,5 @@
+---
+"@hypercerts-org/lexicon": minor
+---
+
+Move schema documentation tables from README.md to auto-generated SCHEMAS.md to reduce git merge conflicts. The SCHEMAS.md file is now auto-generated from lexicon definitions and included in the distributed package.

.gitattributes

@@ -0,0 +1,3 @@
+# Custom merge driver for auto-generated files
+# When SCHEMAS.md has conflicts, regenerate it and use the result
+SCHEMAS.md merge=schemas

.gitignore

@@ -4,3 +4,4 @@ dist/
 generated/
 pnpm-lock.yaml
 /tmp/
+lexicons.md

AGENTS.md

@@ -58,6 +58,8 @@ and type declaration files in `dist/`.
 
 ## Development Commands
 
+**⚠️ IMPORTANT FOR AI AGENTS**: Always run scripts through npm scripts (e.g., `npm run gen-schemas-md`) rather than executing Node.js files directly (e.g., `node scripts/generate-schemas.js`). This ensures proper environment setup and consistency with the project's workflow.
+
 ### Code Generation
 
 ```bash
@@ -70,6 +72,9 @@ npm run gen-index
 # Build distributable bundles
 npm run build
 
+# Generate SCHEMAS.md from lexicon definitions
+npm run gen-schemas-md
+
 # Generate markdown documentation from lexicons
 npm run gen-md
 
@@ -205,6 +210,7 @@ lexicons/               # Source of truth (committed)
 scripts/                # Build scripts (committed)
   create-shims.sh       # Generate type shims for external lexicons
   generate-exports.js   # Auto-generate generated/exports.ts
+  generate-schemas.js   # Auto-generate SCHEMAS.md from lexicons
 
 generated/              # Auto-generated (gitignored)
   index.ts              # Generated client (not exposed)

README.md

@@ -57,7 +57,7 @@
           },
           "measurements": {
             "type": "array",
-            "description": "Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.claim.measurement ",
+            "description": "Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.claim.measurement",
             "items": {
               "type": "ref",
               "ref": "com.atproto.repo.strongRef"

SCHEMAS.md

@@ -22,6 +22,7 @@
   "files": [
     "dist",
     "lexicons",
+    "SCHEMAS.md",
     "CHANGELOG.md"
   ],
   "keywords": [
@@ -38,11 +39,12 @@
   },
   "scripts": {
     "list": "find ./lexicons -name '*.json'",
-    "check": "npm run gen-api && npm run lint && npm run typecheck && npm run build && npm run test",
+    "check": "npm run gen-schemas-md && npm run gen-api && npm run lint && npm run typecheck && npm run build && npm run test",
     "build": "rollup -c && npm run build:types",
     "build:types": "tsc --project tsconfig.build.json",
     "gen-api": "find ./lexicons -name '*.json' | xargs lex gen-api --yes ./generated && ./scripts/create-shims.sh && npm run gen-index",
     "gen-md": "find ./lexicons -name '*.json' | xargs lex gen-md --yes ./lexicons.md",
+    "gen-schemas-md": "node ./scripts/generate-schemas.js",
     "//gen-ts": "UNUSED - use gen-api instead",
     "gen-ts": "find ./lexicons -name '*.json' | xargs lex gen-ts-obj > generated/DO-NOT-USE-lexicons.ts",
     "gen-index": "node ./scripts/generate-exports.js",
@@ -59,7 +61,7 @@
     "changeset": "changeset",
     "version-packages": "changeset version && npm install --package-lock-only",
     "release": "npm run check && changeset publish",
-    "prepare": "husky"
+    "prepare": "husky && ./scripts/setup-merge-driver.sh"
   },
   "dependencies": {
     "@atcute/leaflet": "^1.0.15",