mosaic-headless 1.5.0 → 1.5.1

package/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Build and modify Mosaic Pro (Nextend) sites by writing the underlying data model directly - no visual editor, no DOM. Query the real surface with `mo.py`, which joins every source table to the live sweeps so a lookup leads with the measured verdict rather than the declaration (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, nine designed pages built through the tables themselves, and the delivered page re-read in Chromium at three viewports so a rule that is present, correct and still wrong cannot pass.
 license: "MIT"
 author: "moksa (https://moksaweb.com)"
-version: "1.5.0"
+version: "1.5.1"
 ---
 
 # Headless Mosaic

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

@@ -20,7 +20,7 @@
     "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.5.0"
+    "version": "1.5.1"
   },
   "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": [

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

@@ -20,7 +20,7 @@
     "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.5.0"
+    "version": "1.5.1"
   },
   "loaderBehaviour": "Auto-loads on session start when SKILL.md frontmatter parses successfully.",
   "verified": true,

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

@@ -20,7 +20,7 @@
     "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.5.0"
+    "version": "1.5.1"
   },
   "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,

package/assets/templates/platforms/copilot.json

@@ -20,7 +20,7 @@
     "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.5.0"
+    "version": "1.5.1"
   },
   "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": {

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

@@ -20,7 +20,7 @@
     "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.5.0"
+    "version": "1.5.1"
   },
   "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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mosaic-headless",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "AI-agent skill: build Mosaic Pro (Nextend) WordPress sites by writing the underlying data model directly - 23 custom tables, no visual editor, no DOM. Every node type, style property and node property swept against a live install and asserted on the delivered HTML and compiled CSS. Installs into Claude Code, Cursor, Codex CLI, Gemini CLI, Copilot, Continue, Windsurf and Claude.ai.",
   "keywords": [
     "wordpress",

package/references/failure-modes.md

@@ -188,6 +188,21 @@ wrappers were sitting correctly in the database and in the committed JSON.
 The tell is the byte count: if the size the builder reports and the size you fetch
 disagree, you are not looking at what you wrote.
 
+**And the cache cuts the other way too, which is worse.** Once every tool in the
+toolchain cache-busts, nothing is left looking at the page a visitor receives. A
+build finishes, every check reports green - responsive verified, computed values
+agreed, design audit clean, the entrance animation asserted on seven counts - and
+the site is still serving the previous document to everybody. Measured here: a
+visitor got 141,134 bytes with none of the new work in it while a cache-busted fetch
+of the same URL gave 148,457. Nothing was wrong except that nobody had looked.
+
+`build_site.py` now fetches each page twice at the end of the build, plain and
+cache-busted, and says so when they disagree. It cannot purge the cache - that needs
+credentials a build script has no business holding - but it must not be silent. Two
+fetches of the same live page differ by a few hundred bytes anyway, since nonces and
+ids regenerate per request, so the tolerance is proportional: natural variance
+measured at 0.25%, a stale document at 5%.
+
 `tools/verify_rwd.py` now appends a unique `_v=<ms>` query string and sends
 `Cache-Control: no-cache` on every fetch, so the assertion is always made against the
 document that was actually committed. Do the same in anything else that checks a page

package/tools/build_site.py

@@ -32,6 +32,7 @@ import argparse
 import json
 import os
 import sys
+import urllib.request
 import urllib.parse
 import uuid
 
@@ -148,6 +149,45 @@ def build_page_document(client, cfg, master_id, template_id, tree, surface):
     return len(records)
 
 
+def cache_check(url, _fresh_bytes=None):
+    """Fetch the URL twice - once as a visitor, once cache-busted - and compare.
+
+    Every check in this repo cache-busts, for good reason: a verifier that reads a
+    stale copy reports the previous build. But that means nothing here had ever
+    looked at the page an actual VISITOR receives. A full-page cache in front of
+    WordPress - Varnish on Cloudways, any CDN - keeps serving the old document after
+    a perfectly successful build, and the whole toolchain reports green while the
+    site shows yesterday's page. Measured here: 141,134 bytes to a visitor while the
+    build had just produced 148,457.
+
+    Both fetches happen here, at the same moment, because comparing against a size
+    measured earlier in the build folds in every byte that changed in between. Two
+    fetches of the same live page still differ by a few hundred bytes - nonces and
+    ids are regenerated per request - so the tolerance is proportional: natural
+    variance measured at 0.25%, a stale document at 5%.
+
+    This cannot purge the cache; that needs credentials this tool has no business
+    holding. Silence is the one thing it must not do.
+    """
+    def get(u):
+        req = urllib.request.Request(u, headers={"User-Agent": "Mozilla/5.0"})
+        with urllib.request.urlopen(req, timeout=60) as r:
+            return r.read(), (r.headers.get("Age") or r.headers.get("X-Cache") or "")
+
+    try:
+        sep = "&" if "?" in url else "?"
+        fresh, _ = get("%s%s_v=%d" % (url, sep, uuid.uuid4().int % 10 ** 9))
+        plain, age = get(url)
+    except Exception as exc:                              # noqa: BLE001
+        return "could not compare the cached page: %s" % exc
+
+    if abs(len(plain) - len(fresh)) <= max(512, len(fresh) // 100):
+        return ""
+    return ("STALE CACHE: a visitor gets %d bytes, a fresh fetch gives %d%s"
+            " - purge the page cache or the site keeps serving the old document"
+            % (len(plain), len(fresh), ("  (Age %s)" % age) if age else ""))
+
+
 def main():
     ap = argparse.ArgumentParser()
     ap.add_argument("--config", required=True)
@@ -168,6 +208,9 @@ def main():
         ok = len(body) >= MIN_HEALTHY_BYTES
         print("  %-16s %-7s %6d bytes  %3d nodes  %s" % (
             page["slug"], "OK" if ok else "BROKEN", len(body), n, url))
+        stale = cache_check(url, len(body))
+        if stale:
+            print("  %-16s %s" % ("", stale))
 
 
 if __name__ == "__main__":