Fold hosted-publish learnings: split publish-to-hosted.md, correct upload + mode enum

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude skills for Dynamicweb 10 — organized by task domain, bundled by role.",
-    "version": "4.8.0"
+    "version": "4.9.0"
   },
   "plugins": [
     {

CHANGELOG.md

@@ -3,6 +3,56 @@
 All notable changes to the Dynamicweb Skills plugin are recorded here. The
 `version` field in `.claude-plugin/marketplace.json` tracks these entries.
 
+## [4.9.0]
+
+Splits the publish path into its own reference and folds a second hosted-publish build's
+learnings into it — including a serializer gap that silently empties every product index.
+
+### Added
+- **`dw-demo-base/references/publish-to-hosted.md`** (new): the local→hosted publish playbook,
+  moved out of `online-mode.md` (which now owns the hosted *build* only) and extended with:
+  - **Pre-flight: create custom product fields on the target before the first deserialize.**
+    Product fields are column-backed (`EcomProductField` = a column on `EcomProducts`), and the
+    engine's schema-sync only walks `EcomProductGroupField` — so a deserialize lands definitions
+    whose columns do not exist. The result is a 500 on every product read *and* a `Full` index
+    build that returns `status: ok` while indexing **zero documents**, install-wide. Includes the
+    deadlock (the field can then be neither dropped nor created) and its only exit, plus the
+    duplicate-SystemName trap that re-creates the same zero-document failure.
+  - **Publishing onto an install that already has content**: id collisions on a stock Swift
+    catalog — a variant group whose target twin is a colour group swallows the demo's options and
+    renders no selector at all while the variant products index perfectly; and the variant
+    *combination* table is identity-PK, so its rows never land and **every add-to-cart is silently
+    refused** (the only trace is `Not a valid variant combination` in the event log — the POST still
+    returns 200). Rebuilding the combinations then overwrites the variant rows' own weight/price from
+    the master, which `ProductSave` cannot put back (it no-ops on variant rows) — only a re-deserialize
+    can.
+  - **Indexes**: the repository *definition* travels, the built segments do not (copying them gives
+    a PLP with a product count and no cards); a repository uploaded into a running app needs a
+    restart before its facets resolve.
+  - **Derive-on-save item fields** do not survive a deserialize (the logo-width canary), and the
+    repair must be the **last** write — it is a plain `ParagraphSave`, so any later deserialize
+    reverts it and a publish that ends with "re-deserialize to fix X" undoes every such repair.
+    Plus `IsDryRun` before every hosted deserialize.
+  - Orders ride a plain `SqlTable` predicate, though no shipped example config includes them.
+
+### Changed
+- **`online-mode.md`** — now scoped to building on a hosted install; the publish section moved to
+  the new reference. Two corrections:
+  - **Upload**: `allowOverwrite=true` (an undocumented form field) replaces the delete-before-upload
+    workaround. Success is `model` being a **list**, never `status: ok` — a refused batch reports
+    `ok` with a `duplicates` object and writes nothing, and one pre-existing name drops the batch's
+    new files too.
+  - **Restart ladder**: the CloudHosting control files are a Dynamicweb Cloud affordance, not a
+    property of every hosted install. Confirm the file is *consumed*; a partner-hosted install can
+    accept `recycle.txt`/`restart.txt` and never act on them, which means rung 3 does not exist there.
+- **`serializer-reference.md`** — the predicate `mode` enum is version-scoped: **`Replace`/`Merge` on
+  0.8.x** (`Deploy`/`Seed` are *rejected*, not aliased — `ConfigLoader.ValidatePredicates` throws), the
+  run's mode moves into the JSON body, and `IsDryRun` is available. A config authored for the wrong
+  engine major 500s **every** Serializer call, including the read-only settings query — so
+  `GET /Admin/Api/SerializerSettings` is now prescribed as the one-call config-validity probe.
+- **`dw-demo-swift/references/deserialize-flow.md`** — the 0.6.9-stamped two-pass `?mode=` flow now
+  carries a pointer for 0.8.x callers.
+
 ## [4.8.0]
 
 Adds the local→hosted **publish path** to the online-mode reference and retracts the

README.md

@@ -136,7 +136,7 @@ Browse Dynamicweb source code on GitHub to understand internal APIs, classes, an
 ### Demos (Presales)
 
 **[dw-demo-base](skills/dw-demo-base/SKILL.md)**
-Foundation skill for all demos. Scaffolds the dw10-suite host, wires the Backend MCP and two-layer localhost TLS bypass, installs Playwright MCP, and drops the customisations and customer-context guardrails. Use this first. Also owns the **orchestrator abstraction** ([references/orchestrator.md](skills/dw-demo-base/references/orchestrator.md)) — how a build is driven, GSD primary or the native `/demo:*` command set. Owns the **hosted/cloud fork** ([references/online-mode.md](skills/dw-demo-base/references/online-mode.md)) — building on an install reached only by URL + Admin API key, and publishing a locally-built demo onto one.
+Foundation skill for all demos. Scaffolds the dw10-suite host, wires the Backend MCP and two-layer localhost TLS bypass, installs Playwright MCP, and drops the customisations and customer-context guardrails. Use this first. Also owns the **orchestrator abstraction** ([references/orchestrator.md](skills/dw-demo-base/references/orchestrator.md)) — how a build is driven, GSD primary or the native `/demo:*` command set. Owns the **hosted/cloud fork** ([references/online-mode.md](skills/dw-demo-base/references/online-mode.md)) — building on an install reached only by URL + Admin API key — and the **publish path** ([references/publish-to-hosted.md](skills/dw-demo-base/references/publish-to-hosted.md)) — migrating a locally-built demo onto one.
 
 **[dw-demo-pim](skills/dw-demo-pim/SKILL.md)**
 PIM modelling from a blank DB — product data built from scratch via MCP. Use after `dw-demo-base`.

skills/dw-demo-base/SKILL.md

@@ -30,7 +30,7 @@ Every sister demo skill carries the same "how to run me" header and defers to th
 
 ## Environment fork — local install vs hosted (online) install
 
-The canonical flow below assumes a **local install** (scaffold + SQL Express on the demo machine). When the engagement instead hands you a **site URL + Admin API bearer key** — a vendor-hosted/cloud install with no machine to scaffold on — fork to [references/online-mode.md](references/online-mode.md), which owns the deltas: which canonical steps to skip, the session-start probe (tool availability on hosted installs is **version-dependent** — MCP may or may not be exposed; always probe, never assume), the Management API recipe pack that substitutes for MCP/SQL recipes, and the shared-install discipline. That reference also owns the **publish path** — moving a demo that was built locally onto a hosted install, which is a three-transport migration rather than a deploy button. The always-on rules (surface priority, guarded writes, customer-context, demo philosophy) apply in both modes.
+The canonical flow below assumes a **local install** (scaffold + SQL Express on the demo machine). When the engagement instead hands you a **site URL + Admin API bearer key** — a vendor-hosted/cloud install with no machine to scaffold on — fork to [references/online-mode.md](references/online-mode.md), which owns the deltas: which canonical steps to skip, the session-start probe (tool availability on hosted installs is **version-dependent** — MCP may or may not be exposed; always probe, never assume), the Management API recipe pack that substitutes for MCP/SQL recipes, and the shared-install discipline. Moving a demo that was built locally onto a hosted install is a **migration, not a deploy** — a separate playbook with its own failure modes, owned by [references/publish-to-hosted.md](references/publish-to-hosted.md). The always-on rules (surface priority, guarded writes, customer-context, demo philosophy) apply in both modes.
 
 ## Canonical end-to-end flow
 
@@ -102,7 +102,8 @@ Cloning uses `git` (hence the setup-checks probe that `git` is present, plus `gh
 |---|---|
 | Understand how a demo build is **driven** — the orchestrator abstraction (GSD primary vs the native `/demo:*` command set), GSD detection / deference + `--standalone`, the `agent_skills` keystone, the strictness gradient, and the shared acceptance criteria | references/orchestrator.md |
 | Verify a fresh machine is build-ready (incl. the MSDTC check that AreaCopy `TransactionException`s trace back to) | references/setup-checks.md |
-| **Build on a hosted/cloud install** (URL + Admin API key only — no scaffold, no SQL; Management API create-vs-update semantics, binder shapes, upload-never-overwrites, variants, the flush-then-restart ladder, known API gaps) — and **publish an existing local demo onto one** ("publish this site", "push the demo to the cloud install", "migrate local → hosted": transport map, clean-room deserialize, id remapping, the global settings that never ride a content export) | **references/online-mode.md** |
+| **Build on a hosted/cloud install** (URL + Admin API key only — no scaffold, no SQL; Management API create-vs-update semantics, binder shapes, `allowOverwrite` on upload, variants, the flush-then-restart ladder, known API gaps) | **references/online-mode.md** |
+| **Publish an existing local demo onto a hosted install** ("publish this site", "push the demo to the cloud install", "migrate local → hosted") — pre-flight (custom product fields must exist on the target before the first deserialize), transport map, clean-room deserialize, id collisions on an install that already has content, the global settings that never ride a content export, index rebuild | **references/publish-to-hosted.md** |
 | Ask the demo's DW10 + Swift versions and check out the Distribution layers/editions per-demo | "Versions prompt + Distribution clone/checkout" above + references/setup-checks.md |
 | Scaffold the project | references/scaffold.md |
 | Get MCP working (and verify it) | references/mcp-setup.md |