Schema Review — check the data model before you generate it

Turns a raw collection schema (field-definition JSON) into a reviewable artifact: a skimmable field table (name · type · required · translatable · default · references) plus a small relationships sketch — so the data model can be approved before crouton config generates the Form / List / API / migration from it.

This is the schema analog of the ui-proposal skill, and the foundation of the schema sign-off loop (epic #314): produce the review → it gets posted on the PR → iterate on feedback → only then generate the collection. The schema is the foundation; a wrong field type or missing relationship means regenerating the whole collection, so approving it first is cheap and fixing it after is not.

Why a PNG? GitHub comments can't render raw HTML/CSS. The committed .html is the editable source; the .png is what gets posted (plus the inline Markdown table).

When to use

• An agent has drafted/changed a collection schema (the fieldsFile JSON, or MCP design_schema output) and is about to run crouton config / generate_collection.
• The user asks to "review the schema", "show the data model", "check these fields".
• Skip for non-schema work (no collection / field defs involved).

Review the crouton.config.js alongside the fields. The schema is the data model; crouton.config.js is the generation plan — collections, target layer, features, locales, dialect — and it decides the generated forms / lists / API surface. So the config is part of the same sign-off, presented next to the field tables, not a separate step.

It sits after the machine validate_schema step (which checks the JSON is well-formed) — this is the human gate on top of it.

What it produces

Artifact	Path	Committed?
Review source (HTML)	writeups/schema-reviews/<collection>.html	✅ yes (editable source of truth)
Markdown table	writeups/schema-reviews/<collection>.md	✅ yes (inline-postable)
Rendered image	screenshots/schema-review-<collection>.png	❌ no — screenshots/ is gitignored; it's posted to the PR, not committed

Step 1 — Get the schema JSON

Obtain the field-definition JSON for the collection (the fieldsFile, or the MCP design_schema output). Save it to a file, e.g. /tmp/<collection>.schema.json. The renderer accepts any of these shapes:

• { "collection": "products", "fields": { ... } }
• { "fields": { ... } }
• a flat map { "name": { "type": "string" }, ... } (pass --collection <name>).

Each field follows the crouton schema (see the crouton skill): type, optional meta (required, unique, primaryKey, default, precision/scale, options + displayAs, optionsCollection…), translatable, and refTarget/refScope for relations.

Step 2 — Render the review

node .claude/skills/schema-review/render-schema.mjs /tmp/<collection>.schema.json
# → writes writeups/schema-reviews/<collection>.html + .md, and prints the Markdown table
# options: --collection <name>   --out-dir <dir>

Step 3 — Render to PNG (shared renderer from #308)

node .claude/skills/ui-proposal/render.mjs \
  writeups/schema-reviews/<collection>.html \
  screenshots/schema-review-<collection>.png

Uses the repo's Playwright headless Chromium — offline, no network.

Step 4 — Hand off (review happens on the DIFF)

The committed Markdown is the actionable review surface — not the image. A PNG can't be commented on; the reviewer would have to copy text and describe which field they mean. The .md lands in the PR's "Files changed", one field per row, so the reviewer can click the + on any line and leave an inline comment pinned to that exact field ("make this decimal", "add a slug field here") — no copying, no describing.

• Commit writeups/schema-reviews/<collection>.md and .html (via /commit, scope docs) so the .md appears in the PR diff. This is where feedback goes.
• The PNG is the optional at-a-glance visual — post it in the PR description/comment, but steer feedback to the diff.
• The gate + revision loop that hold crouton config until approval are wired in #316 (reusing the generic approval loop from #310): it reads the inline review comments on the committed .md, revises the schema field-by-field, re-renders, and replies to/resolves each thread. When running this skill by hand, point the reviewer at the committed .md in the diff.

Unresolved relations — the thing this gate exists to catch

A field typed relation with no refTarget is the highest-value thing on the page: it is the one detail that makes the relation buildable, and it is the easiest to approve without noticing. The renderer marks it ⚠ not set in the References column and replaces the relationships sketch with a warning naming each offender. It never reports "No relationships" for a collection that has relation fields.

Do not approve a schema carrying one. Name the collection each points at, and check that collection is actually being generated — a target that doesn't exist produces an import to a missing file and fails the build, minutes later, with an error that names none of this.

If people are the intended target, say so explicitly: in crouton they come from the auth/team side, not a generated collection, so it likely needs a different field type rather than a relation.

Pass --strict to make it a hard gate (exit 1) — use that for a pre-generate check or CI. It is off by default because the decompose apply step calls this inside a best-effort guard, where a non-zero exit would drop the schema artifact from the sign-off comment entirely and hide the problem instead of showing it.

Minted by the #1825 chores POC: assignee and lastDoneBy were approved as untargeted relations, the summary read "No relationships.", the build instruction then invented "references household members/users", the worker turned that into refTarget: "users", and the generated code imported a users collection nobody ever created.

Conventions

• One review per collection; re-render after every schema edit so the artifact never drifts.
• The field table is the source of truth for review — keep it honest (mirror the actual JSON, including primary keys 🔑, unique, defaults, and every relationship).
• Keep it focused on the one collection under discussion.