fix(scripts): render permission-set fields in SCHEMAS.md, add parse context

Two Copilot review fixes on the permission-sets PR:

- generate-schemas.js: permission-set defs (title/detail/permissions) now
  render in SCHEMAS.md instead of producing empty header-only sections.
- generate-exports.js: extract a readLexicon() helper that rethrows
  JSON.parse failures with the offending file path, mirroring
  generate-schemas.js, so codegen errors are traceable.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: 2 people

.changeset/permission-sets-crud.md

@@ -11,3 +11,5 @@ There are **three** sets rather than one because the spec requires it: a permiss
 Permission sets are published as-is (they are the source of truth for what gets published to AT Protocol) but have no TypeScript shape — `lex gen-api` cannot generate code for `permission-set` defs. They are therefore excluded from the codegen globs (`gen-api`/`gen-md`/`gen-ts`) and from `generated/exports.ts`, while still shipping as raw lexicon JSON.
 
 Collection lists are enumerated explicitly because the spec forbids wildcards inside a permission set; they must be kept in sync as record types are added. See `docs/design/permission-sets.md`.
+
+The generated `SCHEMAS.md` reference now renders permission-set entries (title, detail, and the resource/collections/actions each set grants) instead of leaving them as empty sections.

SCHEMAS.md

@@ -9,6 +9,16 @@ Hypercerts-specific lexicons for tracking impact work and claims.
 
 ### `org.hypercerts.authWrite`
 
+**Title:** Manage your Hypercerts data
+
+**Detail:** Create, edit, and delete your Hypercerts records (impact claims, evaluations, funding, and related data).
+
+**Resource:** `repo`
+
+**Collections:** `org.hypercerts.claim.activity`, `org.hypercerts.claim.contribution`, `org.hypercerts.claim.contributorInformation`, `org.hypercerts.claim.rights`, `org.hypercerts.collection`, `org.hypercerts.context.acknowledgement`, `org.hypercerts.context.attachment`, `org.hypercerts.context.evaluation`, `org.hypercerts.context.measurement`, `org.hypercerts.funding.receipt`, `org.hypercerts.workscope.tag`
+
+**Actions:** `create`, `update`, `delete`
+
 ---
 
 ### `org.hypercerts.claim.activity`
@@ -490,6 +500,16 @@ A labeled URL reference.
 
 ### `app.certified.authWrite`
 
+**Title:** Manage your Certified data
+
+**Detail:** Create, edit, and delete your Certified records (profile, badges, follows, wallet links, and related data).
+
+**Resource:** `repo`
+
+**Collections:** `app.certified.actor.organization`, `app.certified.actor.profile`, `app.certified.badge.award`, `app.certified.badge.definition`, `app.certified.badge.response`, `app.certified.graph.follow`, `app.certified.link.evm`, `app.certified.location`, `app.certified.signature.proof`
+
+**Actions:** `create`, `update`, `delete`
+
 ---
 
 ### `app.certified.graph.follow`
@@ -732,6 +752,16 @@ Specifies the sub-string range a facet feature applies to. Start index is inclus
 
 ### `org.hyperboards.authWrite`
 
+**Title:** Manage your Hyperboards data
+
+**Detail:** Create, edit, and delete your Hyperboards records (board configurations and display profiles).
+
+**Resource:** `repo`
+
+**Collections:** `org.hyperboards.board`, `org.hyperboards.displayProfile`
+
+**Actions:** `create`, `update`, `delete`
+
 ---
 
 ### `org.hyperboards.board`

scripts/generate-exports.js

@@ -22,6 +22,22 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const projectRoot = join(__dirname, "..");
 const lexiconsDir = join(projectRoot, "lexicons");
 
+/**
+ * Read and parse a lexicon JSON file, rethrowing parse failures with the
+ * offending file path so codegen errors are traceable (mirrors
+ * scripts/generate-schemas.js).
+ */
+function readLexicon(filePath) {
+  const content = readFileSync(join(lexiconsDir, filePath), "utf-8");
+
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse lexicon ${filePath}: ${message}`);
+  }
+}
+
 /**
  * Recursively find all JSON files in a directory
  */
@@ -163,7 +179,7 @@ function generateIndex() {
     .sort()
     .map((filePath) => ({
       filePath,
-      doc: JSON.parse(readFileSync(join(lexiconsDir, filePath), "utf-8")),
+      doc: readLexicon(filePath),
     }))
     // Permission-set lexicons have no TS shape — lex gen-api cannot codegen them
     // — so they are excluded from `generated/` here, by the SAME content check

scripts/generate-schemas.js

@@ -272,11 +272,38 @@ function generateDescription(description) {
   return description ? [`**Description:** ${description}`, ""] : [];
 }
 
+function generatePermissionSetSection(mainDef) {
+  const output = [];
+
+  if (mainDef.title) output.push(`**Title:** ${mainDef.title}`, "");
+  if (mainDef.detail) output.push(`**Detail:** ${mainDef.detail}`, "");
+
+  const permissions = mainDef.permissions || [];
+  for (const permission of permissions) {
+    const collections = (permission.collection || [])
+      .map((c) => `\`${c}\``)
+      .join(", ");
+    const actions = (permission.action || []).map((a) => `\`${a}\``).join(", ");
+    output.push(`**Resource:** \`${permission.resource}\``, "");
+    if (collections) output.push(`**Collections:** ${collections}`, "");
+    if (actions) output.push(`**Actions:** ${actions}`, "");
+  }
+
+  return output;
+}
+
 function generateMainSection(mainDef, lexicon) {
   const output = [];
 
   if (!mainDef) return output;
 
+  // Permission sets have no properties — render their title/detail/permissions
+  // so the section isn't blank in the reference.
+  if (mainDef.type === "permission-set") {
+    const permOutput = generatePermissionSetSection(mainDef);
+    return { output: permOutput, hasProperties: false, hasPropertyRows: false };
+  }
+
   output.push(...generateDescription(mainDef.description));
 
   // Object types (e.g., celExpression) have no record key