AI schema scaffolding from your existing pages

The agent has five tools:

1. list_observed_blocks — block names + frequencies + the discriminator key the analyser saw on each top-level array.
2. list_shared_subshapes — array fields appearing in 2+ blocks with overlapping inner shapes (the buttons extraction case).
3. validate_schema — checks a candidate against the shape report. Returns "validation OK" or a numbered list of violations with JSONPath of each problem.
4. write_schema_files — commits a validated schema as .norcube/cms/config.yml + per-collection + per-block files in one atomic commit.

Workflow: inspect → find shared shapes → propose → validate → fix → validate → write. Capped at 25 iterations. The agent literally cannot commit an invalid schema — the write tool re-validates and refuses.

The agent never reads every file. It runs against a pre-distilled shape report:

1. One GitHub Tree API call returns every path in the repo (no contents).
2. Path-name heuristic picks the most likely pages directory.
3. Up to 120 files diversity-sampled across subdirectories.
4. Frontmatter parsed for each; block shapes converge quickly (after 12 instances of hero-split, we stop sampling its fields).
5. Report pruned to fit a ~50 KB JSON budget before being sent to the agent.

The agent sees the report, not the files. Three tools operate on the report and the candidate schema — they never read files directly. Worst case: a blog with 5,000 posts and 8 page templates sees ~15 examples of each template, which is plenty to infer shape but won't catch a one-off field that appears on 2 of 5,000 pages. That's a fidelity-for-cost trade we made deliberately.

The validator is the contract that makes "AI-generated schema" safe. Anything below is a hard reject; the agent has to fix the violation before it can commit:

• Missing idKey. When items use a non-default discriminator (_component:, _kind:, …) the array field must declare idKey: "_component" so the editor reads the right key.
• Dangling $ref. Every $ref: must resolve to a block in the blocks registry.
• Missing previews. Every block with title- / description- / image-shaped fields must ship a preview: block — otherwise array items render as opaque "Item #N" rows.
• Chip-shaped fields in description / title slots. badge, tag, status, category go in badges:, not in description:.
• Inlined shape that duplicates a block. If blocks.button exists and any array's items[] has the same field signature inline, the agent must replace the inline entry with { $ref: "button" }.
• Invalid field types. Only the closed type set (text, paragraph, richtext, number, boolean, date, color, range, link, image, file, select, multichoice, group, array) is accepted.

When you re-run "Analyze repo" the agent queues every existing .yml under .norcube/cms/collections/, .norcube/cms/blocks/, and .norcube/cms/inputs/ for deletion in the same commit as the new write. The bundled commit deletes the old files and writes the new ones atomically — same-name files get the new content; renamed or dropped blocks don't leave orphan .yml files behind.

Caveat: this wipes hand-edits unconditionally. While you're iterating on AI output that's the right trade. Once you start polishing by hand, edit the block files directly and stop re-running Analyze — or we'll add a confirmation flow if it becomes a real footgun.