lms-front: Skill for Claude Code

AI Landing-Page Builder (json-render → Puck)

The one idea

A creator types a sentence → an LLM generates a json-render spec constrained to our block vocabulary → we validate it → bridge it to Puck Data → it opens in the existing Puck editor for human drag-and-drop refinement → saved to landing_pages.puck_data.

One vocabulary, two flows. The blocks the AI can emit are the same blocks a human edits in Puck. That's the whole point: AI solves the blank-page problem, Puck handles "let me just tweak this one thing." Every block you wrap for Puck automatically becomes generatable by the AI, and vice-versa. Decision recorded in docs/adr/0001-json-render-puck-landing-builder.md.

creator sentence
   │  POST /api/landing/generate
   ▼  landingCatalog.prompt() + LANDING_AUTHORING_GUIDE  ── constrains the LLM to our blocks
LLM → array spec  { root, elements:[{id,type,propsJson,children}] }
   │  arraySpecToSpec() → normalizeSpec()                ── fold to map, fill required fields
   │  landingCatalog.validate()                          ── REJECT unknown components/props
   ▼  specToPuckData(spec, DEFAULT_PROPS_BY_TYPE)        ── the bridge (backfills defaults)
Puck Data  ──▶  dispatch({type:'setData'})  ──▶  opens live in the Puck editor
   ▼  saved to landing_pages.puck_data

A third flow (July 2026): MCP tools. The MCP server exposes the same pipeline to external AI agents via 8 admin-only tools (lms_get_landing_blocks, lms_list/get/create/update_landing_page, lms_publish/unpublish/delete_landing_page in mcp-server/src/tools/landing-pages.ts). Because mcp-server is built/deployed standalone (Docker context = ./mcp-server), it cannot import lib/json-render/*; instead npm run gen:puck-fields ALSO emits generated mirrors into mcp-server/src/landing/ (puck-fields.generated.ts + catalog-meta.generated.ts from catalog-meta.ts/LANDING_PAGE_CRAFT_GUIDE), and mcp-server/src/landing/{from-puck-fields,to-puck}.ts are kept-in-sync copies of the same-named lib files. After changing any Puck block or the descriptions, re-run npm run gen:puck-fields — it updates both surfaces. If you edit lib/json-render/from-puck-fields.ts or to-puck.ts, apply the same change to the mcp-server copy.