mosaic-headless 1.2.0

package/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: "mosaic-headless"
+description: |
+  Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 properties, 98 style properties with 20 structured value shapes pinned down, 53 style states, 151 element classes, 74 dynamic variables, 12 interaction triggers, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, the design-token and element-class layers verified against compiled CSS, the @VAR() dynamic language verified against rendered output, and nine designed pages built through the tables themselves.
+license: "MIT"
+author: "moksa (https://moksaweb.com)"
+version: "1.2.0"
+---
+
+# Headless Mosaic
+
+Build Mosaic pages by writing the data model directly. The visual builder is one
+client of that model; it is not the format, and you do not need it.
+
+**Scope: page and template construction on a Mosaic site.** Not WordPress site
+health, not plugin audits. If the site is not running Mosaic, this skill does not
+apply — `references/vs-elementor-gutenberg.md` says which skill does.
+
+## The one rule that overrides everything
+
+**Never write a node type, property name, enum value, style key or Free/Pro claim
+from memory. Look it up in `data/`.**
+
+Then check the page. Mosaic has four failure modes and **only one of them changes the
+HTTP status code**:
+
+```
+clean validator rejection   HTTP 200  + an `exceptions` array in the body
+PHP fatal during commit     HTTP 500  (15 of 122 types do this from a plain div)
+structurally invalid node   HTTP 200, committed, row in the DB, and the whole
+                            public page becomes a 54-byte error string
+wrong value SHAPE           HTTP 200, stored, and the CSS rule is simply absent -
+                            or worse, compiles to `transform:none`
+no template for the URL     HTTP 406 with an EMPTY BODY for anyone not logged in
+```
+
+**406 is Mosaic's "no template matched".** `FrontendRenderer` answers
+`TemplateNotFoundException` with `status_header(406)` and prints the explanation
+only for an admin, so a logged-out visitor gets a blank page and a status code
+that looks like a server problem. Two things make it easy to hit:
+
+- **There are TWO ways to bind a template, and `createManualTemplate` is only one
+  of them.** That endpoint takes `resourceQuery=post/<id>` and `post` is the only
+  resource type it registers (`setResourceType('post')`, three call sites), so
+  through it there is no catch-all. But `assign` and `path` are first-class columns
+  on `wp_mosaic_templates`, and a template row committed with `assign:"auto"` and
+  `path:"index.php"` binds to a template PATH instead of a post. Measured A/B on a
+  URL with no template of its own: 406 with no such row, handled with it, 406 again
+  after deleting it. `X-Mosaic-Paths` on any 406 names the paths Mosaic looked for,
+  and `index.php` is in every list.
+
+  **Two limits, both measured.** `adminTemplateEditorInstance` does not return auto
+  templates at all - it listed only the three manual ones - so the admin surface
+  hides them. And an auto template's document has a `node/template/<id>` key but no
+  `template-internal` root: `heal()` builds that skeleton only for templates made
+  through `createManualTemplate`, and committing one directly answers HTTP 500. So
+  the row removes the 406 and I could not then put content in it. Not deployed on
+  the demo site for that reason - a 200 with an empty body is worse signal than a
+  406.
+
+  For `/` specifically the WordPress-side fix is the sound one: point the front page
+  at a post that has a template (`show_on_front=page`, `page_on_front=<id>`).
+- **Activating a theme is not the same as populating it.** A fresh theme has no
+  templates, so between `wp theme activate` and a successful build the whole site
+  is 406 - and if the build fails, it stays that way. Never activate a new theme
+  as a step that can be separated from the commit that fills it.
+
+A successful commit is not evidence of a working page. Fetch the page and check its
+size. `references/failure-modes.md` has all of them, measured.
+
+## What was verified, and how
+
+Everything ran against a live install: WordPress 7.1, WooCommerce 11.1,
+Mosaic Pro 1.0.7, **unlicensed** — the licence gates the theme library and updates,
+not the node factories, so the Pro types register and render regardless.
+
+```
+WRITE PATH   verified end to end over REST
+             theme -> master -> healed node tree -> template -> nodes -> public HTML
+
+NODE SWEEP   122 of 122 node types, ONE PER DOCUMENT, committed then rendered then
+             deleted, asserting each type's attrID against the delivered HTML:
+                 RENDERED    70   id found; tag and classes recorded
+                 COMMITTED   30   row exists, nothing reached the page
+                 COMMIT_5xx  15   PHP fatal on commit
+                 BROKE_PAGE   7   committed, then the whole page died
+             Free 74: 43/22/6/3.  Pro 48: 27/8/9/4.  data/node-verification.csv
+
+STYLE        the states[state][breakpoint][property] shape confirmed by writing it
+             and reading back the compiled CSS; 20 of 22 structured value shapes
+             pinned down the same way. data/style-value-shapes.csv
+
+DESIGN SYS   element classes and collection variables both verified against compiled
+             CSS: an elementClass on the Heading 2 meta emitted a site-wide
+             h2,.M_EL_Text__Heading2{...} rule, and a collection variable emitted
+             :root{--brand: rgb(9, 99, 199)} with background-color:var(--brand).
+             references/design-system.md
+
+DYNAMIC      the @VAR('namespace/name') language verified against rendered output -
+             @VAR('post/title') produced the real post title, @concat/@substr/
+             @fallback all compose over it. 74 variables in
+             data/dynamic-variables.csv. references/dynamic-content.md
+
+PROPERTIES   170 probes over the declared property surface, each value asserted
+             against the delivered markup and the compiled CSS separately.
+             data/property-verification.csv
+
+RWD          569 responsive declarations across two sites asserted against the
+             stylesheet the site actually served - each `_t`/`_m` property matched
+             to its element's generated class inside that breakpoint's own media
+             query. All verified; the checker is itself checked against a poisoned
+             spec so a pass means something. data/rwd-verification.csv
+
+BUILD        nine complete designed pages built through the tables alone and checked
+             in a real browser, hover states included - the ninth uses only design
+             tokens, element-class typography and dynamic content, no hard-coded
+             colour anywhere, plus a real studio homepage rebuilt from the
+             live moksaweb.com. sites/_moksa.py is the one that ships.
+
+MEASURED     114 REST routes, 151 element classes, 59 condition subjects,
+             23 tables / 206 columns - read off the running site.
+
+FROM SOURCE  122 node types, 181 properties (61 with enums), 207 pluggable IDs,
+             122 placement rules, 10 composite default structures, 98 style
+             properties, 53 style states.
+```
+
+**Coverage, stated as a fraction rather than as a headline.** The verification
+counts above are real, but they are not the same as "the surface is verified", and
+the difference is worth being exact about:
+
+```
+node types        122 / 122   swept live, one per document
+node properties   181 / 181   re-probed with a value shaped by each property's
+                              own validator chain: 35 APPLIED, 42 NO_EFFECT,
+                              2 EDITOR_ONLY, 55 NO_HOST (no rendering type
+                              declares them), 47 SKIPPED
+style properties   98 /  98   swept live; 58 COMPILED, 18 ABSENT, 1 NO_ELEMENT,
+                              21 SKIPPED (no test value could be synthesised, and
+                              SKIPPED is never counted as a pass)
+```
+
+**A same-value probe measures the probe, not the surface.** The first property run
+sent the string `MPROP0000X` to all 181 properties regardless of what each wanted,
+and reported 91 NO_EFFECT. The tell was that `tagName` was in that list while the
+entire demo site is built on it. Re-probed with a value derived from the declared
+validator chain - array for `ValidatorArray`, boolean for `ValidatorBoolean`, a legal
+enum member for `ValidatorAcceptedValues` - six of those NO_EFFECTs turn out to work:
+`tagName`, `target`, `rel`, `height`, `size`, `insertLocation`.
+
+**Some properties are gated by a companion.** `target` and `rel` did nothing until
+the node also carried a `url`: `button` and `menu-link` render a `<span>` without one
+and an `<a href>` with it, so an anchor-only attribute has nothing to attach to. A
+NO_EFFECT is only meaningful once the property has been given the context it needs.
+
+Twelve remain NO_EFFECT with a correctly shaped value, `cssClasses` and `attributes`
+among them - recorded as measured-inert-with-this-shape rather than as dead, because
+a third shape may yet be the right one.
+
+**A property that belongs to a `group` is inert when you set it on its own.** This is
+the sweep's one big result and it is exact:
+
+```
+ungrouped  78 properties   58 COMPILED   0 ABSENT    (20 SKIPPED)
+grouped    20 properties    0 COMPILED  18 ABSENT    (1 NO_ELEMENT, 1 SKIPPED)
+```
+
+Zero exceptions in either direction. The 20 are the `borderStyle` per-side longhands
+(12), `outlineStyle` (4) and `gridChildPosition` (4) — so `borderLeftWidth`,
+`outlineColor` and `gridColumnStart` are all instances of one rule rather than three
+oddities. Set the grouped shape instead (`border` takes `{width, style, color}`), or
+use `customStyles`. `data/style-verification.csv` carries the group beside the result
+so the pattern is in the data, not just in this paragraph.
+
+**Known gaps, stated rather than papered over.**
+
+- `backgroundStyle` is the one style property whose shape resisted every attempt — it
+  accepts what you send and emits `background-image:none`. Use `customStyles` for
+  gradients, as the glass and darkglow pages do.
+- **`gridColumnStart` / `gridColumnEnd` / `gridRowStart` / `gridRowEnd` emit nothing.**
+  All four are real entries in `data/style-properties.csv`, under `gridChildPosition`.
+  Measured: 16 `gridColumnStart` declarations committed, zero occurrences of
+  `grid-column` in the delivered CSS. Change the template; you cannot place a child.
+- **Interaction property binding is unsolved.** The trigger, action slot and keyframe
+  timing all reach the browser; `propertyMetas` and per-keyframe `properties` do not.
+  Animate with the CSS transition/state path, which is fully verified.
+- Committing a **condition** has not been driven end to end. The grammar in
+  `references/templates-and-conditions.md` is read from source and from the live
+  metas; an element carrying one rendered as hidden, which is consistent with the
+  condition evaluating false but is not proof the shape was understood.
+
+## Orient yourself in this order
+
+1. `references/data-model.md` — where a page actually lives. Read this first even if
+   you know Elementor; the answer is not `postmeta` and not `post_content`.
+2. `references/write-protocol.md` — the checkout/check/commit sequence and envelopes.
+3. `references/failure-modes.md` — how Mosaic fails, measured. Read before writing.
+4. `references/placement.md` — what may go inside what, and what that table cannot
+   tell you.
+5. `references/styling.md` — how a style value becomes CSS, and the shapes that are
+   silently inert if you write a string.
+6. `references/responsive.md` - the state/breakpoint/property axis, the two
+   breakpoint rows, and the override that can change a property but never remove
+   one. **Read before writing any `_t` or `_m` value.**
+7. `references/design-system.md` — element classes and design tokens. **Read this
+   before styling anything beyond a one-off page**; per-node style is the wrong layer
+   for a real site.
+8. `references/dynamic-content.md` — the `@VAR()` language. The syntax is not
+   guessable, and a wrong guess renders as literal text rather than an error.
+9. `references/templates-and-conditions.md` — how Mosaic picks a template, and the
+   condition grammar shared by templates, elements, interactions and form actions.
+10. `references/interactions.md` — the JavaScript animation system, and how far it is
+   verified.
+11. `references/vs-elementor-gutenberg.md` — which builder habits transfer.
+
+## The data files
+
+| file | rows | source |
+|---|---|---|
+| `data/node-verification.csv` | 122 | **swept live** — outcome, rendered tag and classes, page bytes, failure detail |
+| `data/node-types.csv` | 122 | source — slug, label, edition, aliases, data class |
+| `data/node-properties.csv` | 181 | source — property, validator chain, **accepted enum values**, `supportsInherit` |
+| `data/placement-rules.csv` | 122 | source — which children each type accepts |
+| `data/default-children.csv` | 10 | source — what a composite type needs **inside** it |
+| `data/style-properties.csv` | 98 | source — every settable CSS property and its value shape |
+| `data/style-value-shapes.csv` | 22 | **probed live** — the exact JSON shape for each structured value, and what it compiled to |
+| `data/style-states.csv` | 53 | source — state IDs with their exact CSS selector templates |
+| `data/property-verification.csv` | 170 | **probed live** — per-property effect on markup vs CSS, with unprovable enums marked INCONCLUSIVE |
+| `data/node-property-verification.csv` | 181 | **swept live** — each property probed with a value shaped by its own validator chain, on a type that declares it |
+| `data/style-verification.csv` | 98 | **swept live** — every style property written to a page and checked against the compiled CSS, with its group beside the result |
+| `data/rwd-verification.csv` | 569 | **checked live** - every `_t`/`_m` declaration vs the served stylesheet, with status per row |
+| `data/element-classes.csv` | 151 | **live** — the built-in class metas; their IDs are what an `elementClass` record must use |
+| `data/dynamic-variables.csv` | 74 | source — every `@VAR('ns/name')` expression, by namespace |
+| `data/evaluator-functions.csv` | 19 | source — the `@` functions with their arity |
+| `data/interaction-types.csv` | 12 | source — trigger types, `timed` vs `progress` |
+| `data/animatable-properties.csv` | 22 | source — what a keyframe can drive (**not** the same set as the style properties) |
+| `data/condition-subjects.csv` | 59 | **live** — condition subjects per context |
+| `data/condition-comparators.csv` | 12 | **live** — comparators and their operator sets |
+| `data/pluggables.csv` | 207 | source — every `setID()` by registry |
+| `data/rest-routes.csv` | 114 | **live** — method, path, args |
+| `data/db-columns.csv` | 206 | **live** — every column of all 23 tables |
+
+## Building a page
+
+`tools/build_page.py` consumes a declarative spec and commits it through the verified
+write path, refusing anything the tables say is unsafe. `tools/build_site.py` does the
+same for a whole site: one master carrying the header and footer, one template document
+per page.
+
+**`sites/_moksa.py` is the worked example** - a real studio homepage (hero, statistics,
+services, a nine-item work list, products, testimonials, CTA, footer) generated as a
+spec and committed entirely through the tables. Read it for the shape of a real build:
+the `bp()` breakpoint helper, the `code` node that carries the keyframes, the glass
+header, and `apply_type()`.
+
+A spec can carry a `theme` block, which is how a real site should be styled — design
+tokens and element-class typography rather than per-node values:
+
+```jsonc
+"theme": {
+  "variables": {"--brand": {"type": "color", "value": "rgb(13,108,102)"}},
+  "elementClasses": {"Heading 1": {"&": {"_": {"color": {"token": "--brand"}}}}}
+}
+```
+
+`{"token": "--brand"}` anywhere in a style resolves to the `{"var": "<uuid>"}`
+reference the compiler wants.
+
+**Two brands in one theme need namespaced tokens and no element classes at all.**
+Collection variables and element classes are both theme-global: two specs that each
+declare `--ink` produce one `:root` with duplicate declarations, and two specs that
+each style `Heading 1` produce one set of rules. Whichever committed last wins, for
+every page. `sites/_moksa.py` namespaces its tokens (`--mk-*`) and bakes the type
+system onto the nodes with `apply_type()` instead of using element classes, which is
+what lets it share an install with a completely different design.
+
+Whole themes move between installs with `theme_export.php` / `theme_import.php`.
+A theme is a themeID scattered across nineteen tables, and every one of them has a
+COMPOSITE primary key of `(themeID, ID)` — so an import can keep every internal id
+and rewrite nothing but the theme, which means no id remapping and nothing left
+dangling. Round-tripped and verified: a full theme exported, re-imported as a copy,
+and the copy served byte-identical pages.
+
+`copy_styles.py` pushes one node's style onto others by attrID or prefix, optionally
+only certain `state.breakpoint` slices, and shows the diff before writing.
+
+```bash
+wp eval-file tools/bootstrap_probe_theme.php     # licence-free scratch theme
+python tools/build_all.py --config sweep.json    # reset + build every design
+```
+
+Rebuilding a single page without a reset leaves an orphan template bound to the same
+post — `build_all.py` resets first for that reason.
+
+## Facts worth knowing before you look anything up
+
+- **The REST namespace contains the plugin version** (`/wp-json/mosaic/v1.0.7`). Read
+  it from `mosaicOptions.rest_api_url`, never hardcode.
+- **`ordering` is a fractional-index string**, not a number.
+- **The tree is a `parentID` column**, not nesting. There is no page-level JSON blob.
+- **Everything is scoped to a `themeID`**, breakpoints included.
+- **A post is a target, not a container.** Templates bind to posts through
+  `mosaic_template_assigns`; one template serves many posts.
+- **Only `wp_mosaic_locks` existing** means a half-installed Mosaic. The other 22
+  tables appear when an admin loads `/wp-admin/admin.php?page=mosaic`.
+- **Commit has side effects.** `heal()` runs inside it and creates breakpoints,
+  collections and child nodes you never sent. Take every revision in the response.
+- **`modified_gmt` is server-assigned.**
+- **Styling hangs on the generated `.M_EL<n>` class, not your `attrID`**, and that
+  number is not stable. The sibling `M_EL_<Type>` class is.
+- **`body{opacity:0}`** — the theme reveals itself from JavaScript. Screenshot tooling
+  must let scripts run or it captures a blank page.
+
+## Rendered-tag facts you would otherwise guess wrong
+
+- **`button` renders as `<span>`**, not `<button>`. So do `menu-link` and `wysiwyg-link`.
+- **`text` renders as `<div>` by default** — set `tagName` for `<h1>`, `<p>` and so on.
+- **Eight types emit custom elements**: `<mosaic-dropdown>`, `<mosaic-navbar>`,
+  `<mosaic-tabs>`, `<mosaic-accordion>`, `<mosaic-vimeo>`, `<mosaic-youtube>` and
+  friends. A selector written against `div`/`nav` misses all of them.
+- **`icon` renders inline `<svg>`.**
+
+## Regenerating everything
+
+```bash
+python tools/extract_node_types.py       <plugin-root> data/
+python tools/extract_pluggables.py       <plugin-root> data/
+python tools/extract_placement.py        <plugin-root> data/
+python tools/extract_default_children.py <plugin-root> data/
+python tools/extract_style_properties.py <plugin-root> data/
+python tools/extract_interactions.py     <plugin-root> data/
+python tools/extract_dynamic_variables.py <plugin-root> data/
+python tools/capture_live.py             data/          # from data/raw/*.json
+                                                        # (raw dumps are gitignored;
+                                                        #  re-capture from a live site)
+
+# against a scratch site - DESTRUCTIVE, never point at production
+python tools/sweep_node_types.py --config sweep.json --setup
+python tools/sweep_node_types.py --config sweep.json --sweep --edition all
+python tools/sweep_properties.py --config sweep.json
+python tools/verify_rwd.py --config sweep.json --site sites/moksa.json --csv data/rwd-verification.csv
+python tools/sweep_style_properties.py --config sweep.json --page moksa --csv data/style-verification.csv
+python tools/sweep_node_properties.py  --config sweep.json --page moksa --csv data/node-property-verification.csv
+wp eval-file tools/theme_export.php active > theme.json
+wp eval-file tools/theme_import.php theme.json "Copy" rebind activate
+python tools/probe.py --config lab.json --cases cases.json   # ad-hoc measurement
+python tools/check_placement_predicts.py
+```
+
+`bootstrap_probe_theme.php` exists because Mosaic's own new-theme flow calls
+`account.mosaicbuilder.com` and needs a licence. `EditorInstanceWithNewTheme->heal()`
+does not — which is what made a licence-free fixture, and therefore this whole
+verification, possible.

package/assets/templates/platforms/claude-ai.json

@@ -0,0 +1,34 @@
+{
+  "platform": "claude-ai",
+  "displayName": "Claude.ai (web app)",
+  "installType": "zip-upload",
+  "folderStructure": {
+    "projectRoot": null,
+    "globalRoot": null,
+    "skillPath": "mosaic-headless.zip",
+    "filename": "SKILL.md"
+  },
+  "sections": {
+    "skill": true,
+    "references": true,
+    "tools": false,
+    "data": true,
+    "sites": true
+  },
+  "frontmatter": {
+    "name": "mosaic-headless",
+    "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
+    "license": "MIT",
+    "author": "moksa (https://moksaweb.com)",
+    "version": "1.2.0"
+  },
+  "loaderBehaviour": "Upload via Settings -> Skills -> Upload. Claude.ai parses SKILL.md frontmatter and surfaces the skill in your library. The extraction tool (extract-block-schema.php) needs a live WP-CLI connection and won't run in the sandbox; use it from a local terminal against your own site instead.",
+  "uploadSteps": [
+    "1. Run: python tools/install-skill.py claude-ai --to ./build (creates elementor-headless.zip)",
+    "2. Open Claude.ai -> Settings -> Skills -> Upload",
+    "3. Pick the generated zip; the skill appears in your library",
+    "4. New chats auto-invoke when you ask to build/modify an Elementor page programmatically"
+  ],
+  "verified": true,
+  "verifiedAsOf": "2026-09-06"
+}

package/assets/templates/platforms/claude-code.json

@@ -0,0 +1,28 @@
+{
+  "platform": "claude-code",
+  "displayName": "Claude Code",
+  "installType": "full",
+  "folderStructure": {
+    "projectRoot": ".claude",
+    "globalRoot": "~/.claude",
+    "skillPath": "skills/mosaic-headless",
+    "filename": "SKILL.md"
+  },
+  "sections": {
+    "skill": true,
+    "references": true,
+    "tools": true,
+    "data": true,
+    "sites": true
+  },
+  "frontmatter": {
+    "name": "mosaic-headless",
+    "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
+    "license": "MIT",
+    "author": "moksa (https://moksaweb.com)",
+    "version": "1.2.0"
+  },
+  "loaderBehaviour": "Auto-loads on session start when SKILL.md frontmatter parses successfully.",
+  "verified": true,
+  "verifiedAsOf": "2026-09-06"
+}

package/assets/templates/platforms/codex-cli.json

@@ -0,0 +1,33 @@
+{
+  "platform": "codex-cli",
+  "displayName": "OpenAI Codex CLI",
+  "installType": "full",
+  "folderStructure": {
+    "projectRoot": ".codex",
+    "globalRoot": "~/.codex",
+    "skillPath": "skills/mosaic-headless",
+    "filename": "SKILL.md"
+  },
+  "sections": {
+    "skill": true,
+    "references": true,
+    "tools": true,
+    "data": true,
+    "sites": true
+  },
+  "frontmatter": {
+    "name": "mosaic-headless",
+    "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
+    "license": "MIT",
+    "author": "moksa (https://moksaweb.com)",
+    "version": "1.2.0"
+  },
+  "loaderBehaviour": "Confirmed (2026-07-11): Codex CLI natively supports the SKILL.md spec. Place SKILL.md under .codex/skills/<name>/ (project) or ~/.codex/skills/<name>/ (personal) and Codex loads the name+description at session start, then the full body on demand. A parallel, broader convention .agents/skills/ (searched from cwd up to repo root, then ~/.agents/skills/) also exists across multiple tools - if your Codex CLI version prioritizes that path instead, mirror the same SKILL.md there.",
+  "verified": true,
+  "verifiedAsOf": "2026-09-06",
+  "verificationNote": "Upgraded from unverified: as of 2026-07-11 this is documented, native behaviour, not best-effort. Still confirm against your specific Codex CLI version since .agents/skills/ vs .codex/skills/ precedence can vary by build.",
+  "embedReferences": [
+    "data-model.md",
+    "failure-modes.md"
+  ]
+}

package/assets/templates/platforms/continue.json

@@ -0,0 +1,31 @@
+{
+  "platform": "continue",
+  "displayName": "Continue (continue.dev)",
+  "installType": "rule",
+  "folderStructure": {
+    "projectRoot": ".continue",
+    "globalRoot": "~/.continue",
+    "skillPath": "rules",
+    "filename": "mosaic-headless.md"
+  },
+  "sections": {
+    "skill": true,
+    "references": false,
+    "tools": false,
+    "data": false,
+    "sites": false
+  },
+  "frontmatter": {
+    "name": "mosaic-headless",
+    "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
+    "alwaysApply": false
+  },
+  "loaderBehaviour": "Continue reads .continue/rules/*.md as Rules. Set alwaysApply: true to attach to every chat, or leave false and rely on the description for relevance matching. Rule files load in lexicographic order if you split this into several numbered files. References must be embedded inline; the installer concatenates key reference files into the rule body.",
+  "embedReferences": [
+    "data-model.md",
+    "failure-modes.md",
+    "responsive.md"
+  ],
+  "verified": true,
+  "verifiedAsOf": "2026-09-06"
+}

package/assets/templates/platforms/copilot.json

@@ -0,0 +1,46 @@
+{
+  "platform": "copilot",
+  "displayName": "GitHub Copilot",
+  "installType": "full",
+  "folderStructure": {
+    "projectRoot": ".github",
+    "globalRoot": null,
+    "skillPath": "skills/mosaic-headless",
+    "filename": "SKILL.md"
+  },
+  "sections": {
+    "skill": true,
+    "references": true,
+    "tools": true,
+    "data": true,
+    "sites": true
+  },
+  "frontmatter": {
+    "name": "mosaic-headless",
+    "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
+    "license": "MIT",
+    "author": "moksa (https://moksaweb.com)",
+    "version": "1.2.0"
+  },
+  "loaderBehaviour": "CHANGED as of 2026-07-11: GitHub Copilot added a proper '.github/skills/' Agent Skills directory (December 2025), alongside the older single-file .github/copilot-instructions.md convention. This config targets the new skills-directory form. If your Copilot version predates this (pre Dec 2025), use the instructions-append fallback instead (see fallback below).",
+  "fallback": {
+    "installType": "instructions-append",
+    "projectRoot": ".github",
+    "filename": "copilot-instructions.md",
+    "appendMarker": "<!-- BEGIN: elementor-headless -->",
+    "appendMarkerEnd": "<!-- END: elementor-headless -->",
+    "embedReferences": [
+      "data-model.md",
+      "control-types.md",
+      "responsive.md"
+    ],
+    "note": "Use this if your Copilot version does not support .github/skills/ Agent Skills yet."
+  },
+  "verified": true,
+  "verifiedAsOf": "2026-09-06",
+  "verificationNote": "The exact frontmatter/loading contract for .github/skills/ SKILL.md was not independently confirmed byte-for-byte at write time - verify against current GitHub Copilot docs before relying on it for a production install.",
+  "embedReferences": [
+    "data-model.md",
+    "failure-modes.md"
+  ]
+}

package/assets/templates/platforms/cursor.json

@@ -0,0 +1,36 @@
+{
+  "platform": "cursor",
+  "displayName": "Cursor",
+  "installType": "rule",
+  "folderStructure": {
+    "projectRoot": ".cursor",
+    "globalRoot": "~/.cursor",
+    "skillPath": "rules",
+    "filename": "mosaic-headless.mdc"
+  },
+  "sections": {
+    "skill": true,
+    "references": false,
+    "tools": false,
+    "data": false,
+    "sites": false
+  },
+  "frontmatter": {
+    "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
+    "globs": [
+      "**/*.php",
+      "**/wp-content/**",
+      "**/*.json",
+      "**/*.py"
+    ],
+    "alwaysApply": false
+  },
+  "loaderBehaviour": "Cursor reads .cursor/rules/*.mdc as Project Rules. Set alwaysApply: true to auto-attach to every chat, or leave false to attach when filename globs match. Cursor does NOT load referenced files automatically - embed key content inline; keep the rule under ~6KB. Subdirectories are supported (.cursor/rules/wp/x.mdc) if you want to split this up further.",
+  "embedReferences": [
+    "data-model.md",
+    "failure-modes.md",
+    "responsive.md"
+  ],
+  "verified": true,
+  "verifiedAsOf": "2026-09-06"
+}

package/assets/templates/platforms/gemini-cli.json

@@ -0,0 +1,33 @@
+{
+  "platform": "gemini-cli",
+  "displayName": "Gemini CLI",
+  "installType": "full",
+  "folderStructure": {
+    "projectRoot": ".gemini",
+    "globalRoot": "~/.gemini",
+    "skillPath": "skills/mosaic-headless",
+    "filename": "SKILL.md"
+  },
+  "sections": {
+    "skill": true,
+    "references": true,
+    "tools": true,
+    "data": true,
+    "sites": true
+  },
+  "frontmatter": {
+    "name": "mosaic-headless",
+    "description": "Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface (122 node types, 181 node properties, 98 style properties, 53 style states, 151 element classes, 74 dynamic variables, 114 REST routes, 23 tables) instead of guessing, with every node type placed on a live site one at a time and asserted against the delivered HTML, every style and node property swept against the compiled CSS and markup, and 569 responsive declarations checked against the stylesheet the site actually served.",
+    "license": "MIT",
+    "author": "moksa (https://moksaweb.com)",
+    "version": "1.2.0"
+  },
+  "loaderBehaviour": "CHANGED as of 2026-07-11: Gemini CLI now natively supports the same SKILL.md standard as Claude Code and Codex CLI - the same directory-based skill works unmodified. Gemini CLI discovers skills in this precedence order: built-in, extension skills, ~/.gemini/skills/ (personal), .gemini/skills/ (project, shared via version control). At session start Gemini injects each discovered skill's name+description into the system prompt and calls activate_skill when a task matches.",
+  "verified": true,
+  "verifiedAsOf": "2026-09-06",
+  "verificationNote": "This is a DIFFERENT convention than the older .gemini/extensions/<name>/GEMINI.md extension-wrapper approach some skills still ship - that approach still works for bundling a skill inside a distributable extension, but is no longer the simplest or only path for a standalone skill install. Re-check before assuming either convention if this drifts again.",
+  "embedReferences": [
+    "data-model.md",
+    "failure-modes.md"
+  ]
+}

package/assets/templates/platforms/windsurf.json

@@ -0,0 +1,34 @@
+{
+  "platform": "windsurf",
+  "displayName": "Windsurf (now Devin Desktop)",
+  "installType": "rule",
+  "folderStructure": {
+    "projectRoot": ".devin",
+    "globalRoot": null,
+    "skillPath": "rules",
+    "filename": "mosaic-headless.md"
+  },
+  "sections": {
+    "skill": true,
+    "references": false,
+    "tools": false,
+    "data": false,
+    "sites": false
+  },
+  "frontmatter": null,
+  "loaderBehaviour": "CHANGED as of 2026-07-11: Cognition rebranded Windsurf to 'Devin Desktop' on 2026-06-02 (windsurf.com now redirects to devin.ai). New installs should target .devin/rules/*.md as plain markdown (no special frontmatter - group related content with XML-style tags like <workflow>...</workflow>). The old .windsurf/rules/*.md path is kept working as a fallback for pre-rebrand setups. Character limits apply: keep each rule file under ~12,000 characters. References must be embedded inline since Windsurf/Devin does not load referenced files automatically.",
+  "fallback": {
+    "projectRoot": ".windsurf",
+    "skillPath": "rules",
+    "filename": "elementor-headless.md",
+    "note": "Use this path instead if your installation predates the Devin Desktop rebrand and .devin/rules/ is not recognised."
+  },
+  "embedReferences": [
+    "data-model.md",
+    "failure-modes.md",
+    "responsive.md"
+  ],
+  "verified": true,
+  "verifiedAsOf": "2026-09-06",
+  "verificationNote": "Verify which product name/path applies to your install before running - this is the platform most likely to keep shifting given the recent rebrand."
+}