@awesomate/hosting-mcp 0.22.1 → 0.22.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "description": "Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases",
   "license": "UNLICENSED",
   "type": "module",

package/skill/awesomate-hosting/SKILL.md

@@ -88,6 +88,9 @@ wrong account) · `references/connect-troubleshooting.md` (bootstrap, sandbox/
 proxy failures, resuming a connect, support report) ·
 `references/rest-fallback.md` (no `awesomate_*` tools — serve over REST) ·
 `references/voice.md` (how to talk to a non-technical owner).
+`references/wordpress-launch-checks.md` (what to MEASURE in a real browser after any theme,
+template or page deploy — boxed sections, missing logo/favicon, the post-domain re-key, http asset
+URLs — every item a defect an owner reported before the agent noticed).
 
 ## After creating a site
 
@@ -310,6 +313,11 @@ scripts/deploy.sh --from ~/Studio/mysite --domain mysite.awesomate.site --with-d
 Never deploy without confirming with the user first, and always report the
 snapshot id and the verified live status.
 
+**"Verified live status" means a real browser at 390, 768, 844×390, 1024 and 1440px, not a 200 from curl** — the in-between widths are where a header wraps and only the owner's iPad notices.
+Run the checklist in `references/wordpress-launch-checks.md` — full-bleed sections, gutters,
+logo and favicon present, fonts loaded, no broken images, a real 404 — before saying done. Every
+item on it was reported by a site owner after an agent had already said done.
+
 ## 5a. Staging on awesomate.dev (Support Plus+)
 
 The middle tier between "edit live" and "local Studio": a private full copy of

package/skill/awesomate-hosting/references/wordpress-launch-checks.md

@@ -0,0 +1,140 @@
+# WordPress launch checks — what to verify after deploying a theme or content
+
+Every item here was a real defect that shipped to a live client site and was reported by the
+owner, not caught by the agent. Each one looked fine in the generated code and was only visible
+in a browser — so the rule is: **after any theme, template or page deploy, load the live site in a
+real browser at 390px and 1440px and MEASURE, before telling the user it is done.**
+
+## 1. Sections boxed with white strips at the sides (the "margins are off" report)
+
+**Symptom:** coloured section backgrounds stop short of the viewport edges, leaving white strips;
+on a phone the text sits hard against the coloured band with no gutter. The home page often looks
+fine while every inner page is wrong.
+
+**Cause:** the inner-page template gives the **post-content block its own `layout`**:
+`<!-- wp:post-content {"layout":{"type":"constrained"}} /-->`. That boxes every child group to
+`contentSize` and strips its side padding. A front page written as `<!-- wp:post-content /-->`
+(no layout) does not have the problem — which is why only some pages break.
+
+**Fix:** post-content carries **no layout attribute** in templates whose content is built from
+full-bleed section groups. Each section group is `{"layout":{"type":"constrained"}}` itself, so its
+background runs edge to edge while its content is constrained. Keep a constrained post-content
+only for deliberately narrow long-form templates (legal, single post), where every section is white
+anyway.
+
+**Measure it (Playwright, or DevTools console):**
+```js
+const g = document.querySelector('main .wp-block-group.has-background');
+const r = g.getBoundingClientRect();
+const fullBleed = r.left <= 1 && r.width >= innerWidth - 1;      // must be true
+const inset = g.querySelector('h1,h2,p').getBoundingClientRect().left - r.left; // ≥16 on a phone
+```
+
+Two related spacing faults usually travel with it:
+- **Every `<section>` converted to a 96px-top-and-bottom group.** A page header flowing into its
+  content then stacks 192px of dead space. Padding must follow the design's section types (a full
+  section, a page header, a bare container), not one flat value.
+- **WordPress's block gap opens a white line between two coloured bands.** Give section groups
+  `"margin":{"top":"0","bottom":"0"}`.
+- **A fixed root gutter** (`styles.spacing.padding` = 40px) is far too wide on a phone. Use a
+  responsive value, e.g. `min(40px, 5vw)`.
+
+## 2. Logo missing, no favicon
+
+**Symptom:** the header and footer show no logo at all; the browser tab has no icon.
+
+**Cause:** `<!-- wp:site-logo /-->` renders **nothing** until a logo is set in Site Identity
+(`custom_logo` theme mod), and no `<link rel="icon">` is emitted until `site_icon` is set. A fresh
+install has neither, and the media library is empty. On these hosts **SVG uploads are disabled**
+(`image/svg+xml` is not an allowed mime type), so the brand's SVGs cannot be uploaded as media.
+
+**Fix, both halves:**
+- Header/footer logos from the **theme's own files**, not media: make the header and footer
+  *patterns* (PHP) included from the parts —
+  `<!-- wp:pattern {"slug":"<theme>/header"} /-->` in `parts/header.html` — so the pattern can use
+  `get_theme_file_uri('assets/logos/logo.svg')`. This also lets the footer use the on-dark variant
+  while the header uses the primary, which a single Site Identity logo cannot do.
+- Still set Site Identity, because WordPress uses it elsewhere:
+  `wp media import logo.png --porcelain` → `wp theme mod set custom_logo <id>`;
+  `wp media import icon-512.png --porcelain` → `wp option update site_icon <id>`.
+  The site icon must be a **PNG, square, ≥512px** — make one from the brand emblem with
+  transparent padding rather than uploading a rectangular PNG.
+
+**Verify:** the live HTML contains an `<img alt="…">` in the header and `<link rel="icon"`, and both
+URLs return 200 with an image content type.
+
+## 3. The hub re-keys a site when a custom domain becomes its primary
+
+After a custom domain is attached and made primary, `GET /api/client-hosting/sites` reports the
+site under **the new domain** (`domain: example.com`), and per-site endpoints keyed by the old
+`siteN.<slug>.awesomate.site` name return **404** — including the snapshot call, which will abort a
+snapshot-first deploy that worked yesterday. Read `/sites` and use the `domain` it reports.
+
+## 4. Content seeded over WP-CLI stores `http://` asset URLs
+
+Pages created with `wp eval-file` / `wp post create` while the install is still on its
+`*.awesomate.site` address store theme asset URLs as `http://<install host>/...`. A later
+`wp search-replace https://<install host> https://example.com` misses every one of them because of
+the scheme. Replace on the **bare host**: `wp search-replace <install-host> example.com --all-tables
+--precise`, then recount with `LIKE '%<install-host>%'`.
+
+## 5. New pattern files render as nothing until the theme Version changes
+
+**Symptom:** you add `patterns/header.php` (or any new pattern) to a live theme, deploy it, and
+`<!-- wp:pattern {"slug":"theme/header"} /-->` renders an empty string — no error, no logo, nothing.
+Patterns that already existed keep working, which makes the new one look broken rather than
+unregistered.
+
+**Cause:** WordPress caches the theme's `patterns/` directory listing in a transient keyed by the
+theme's `Version:` header (`style.css`). A new file is not seen until that key changes.
+
+**Fix:** bump `Version:` in `style.css` on every deploy that adds, removes or renames a pattern
+file. Verified: the same deploy with `0.1.0 → 0.2.0` registered the patterns instantly. Treat the
+version bump as part of the deploy, not a release ceremony.
+
+## 6. The header wraps between 600px and ~1000px (iPad, phone in landscape)
+
+**Symptom:** the owner says the margins are "bad again" on an iPad or a phone turned sideways, but
+every band measures full-bleed. What they are seeing is the **header**: logo and nav links on one
+row, the buttons dropped to a second row on the left, and a slab of white under them.
+
+**Cause:** core's navigation block collapses to the hamburger only below **600px**. Between 600 and
+roughly 1000px the logo, the links and the header buttons all try to share one flex row, and the
+row wraps. It looks fine on a phone (collapsed) and on a desktop (fits), which is exactly why phone
+and desktop checks both pass while the owner's iPad does not.
+
+**Fix (theme CSS, the block has no breakpoint setting):**
+```css
+.site-header .nav-row { flex-wrap: nowrap; }
+@media (max-width: 1023px) {
+  .site-header .wp-block-navigation { order: 3; }                                  /* hamburger last */
+  .site-header .wp-block-navigation__responsive-container:not(.is-menu-open) { display: none !important; }
+  .site-header .wp-block-navigation__responsive-container-open:not(.always-shown) { display: flex !important; }
+}
+```
+Two faults travel with it at the same widths: core stacks **columns to a single column below
+782px**, so a three-card row becomes a tower on an iPad in portrait (make 3+ column rows two-up
+between 600 and 781 with `display:grid` on `.wp-block-columns:has(> .wp-block-column:nth-child(3))`);
+and a **fixed 96px section padding** is half the screen on a landscape phone — make the section
+spacing preset fluid, e.g. `clamp(64px, 6.7vw, 96px)`.
+
+**Verify at 390, 600, 768, 844×390, 1024 and 1440** — never just phone and desktop. The header
+test: the logo and the primary button share a row (their `getBoundingClientRect().top` differ by
+less than 24px), the hamburger is visible up to 1023 and the links from 1024.
+
+## The launch checklist
+
+Run in a real browser against the LIVE domain at **390, 768, 844×390, 1024 and 1440** — the in-between
+widths are where headers wrap — before reporting done:
+
+1. Every coloured section is full-bleed (`getBoundingClientRect().left <= 1`) with text inset ≥16px.
+2. No horizontal overflow (`documentElement.scrollWidth <= clientWidth + 1`).
+3. Header shows the logo; `<link rel="icon">` is present; both URLs return 200.
+4. `document.fonts` reports the brand faces `loaded` (self-hosted fonts actually shipped).
+5. Zero broken images (`img.complete && naturalWidth > 0`), and zero assets still on the install host.
+6. A nonsense URL returns **404** with the theme's 404 template, not a 200 page.
+7. Section order matches the design (read the `h1,h2` sequence), and neither nav nor decorative
+   marks appear inside page content.
+8. The header is one row at every width above, with the hamburger up to 1023 and the links from 1024.
+9. If the deploy added pattern files, the theme `Version:` was bumped and every `wp:pattern`
+   in the parts actually rendered (an unregistered slug renders as empty, silently).