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

[Justinvolved]

What surfaced this

A second local→hosted publish. One serializer gap had an outsized blast radius, and two pieces of existing guidance turned out to be wrong.

The headline — a silent, install-wide index kill

Custom product fields are column-backed: EcomProductField is a physical column on EcomProducts. A SqlTable predicate deserializes the definition rows faithfully, and nothing creates the columns — the engine's schema-sync only walks EcomProductGroupField.

The target then lands with field definitions whose columns do not exist, and:

• every product read returns HTTP 500 whose title is the bare field name;
• every Full index build returns status: ok while indexing zero documents — install-wide, including repositories the demo never touched;
• the PLP renders an empty grid while still printing its product count.

Only the first of those looks like an error. BuildIndex reporting ok is what makes this expensive.

It also deadlocks: once the definitions exist without columns, the field can be neither dropped (ALTER TABLE DROP COLUMN failed because column '<F>' does not exist) nor created (system name already in use). The one exit — re-saving the existing field provisions the column — is documented, along with the duplicate-SystemName trap that reproduces the same zero-document failure if you create the field via the API and then deserialize.

Pre-flight fix: create the product fields on the target with ProductFieldSave before the first deserialize.

Routed to the engine as well — the durable fix is to extend schema-sync to the column-backed path and to fail loudly rather than index nothing. Filed in the Foundry learnings inbox.

The split

online-mode.md had grown to cover two different jobs (build on a hosted install vs migrate a local demo onto one) and was at the size guideline. The publish playbook moves to a new references/publish-to-hosted.md, extended with:

• Id collisions on an install that already has content. Most expensive: a variant group whose target twin is a colour group — the demo's options deserialize into it, Swift renders colour swatches, and the PDP shows no selector at all while the variant products index perfectly. Also EcomGroupRelations (the target's hierarchy wins unless you ship it) and relation rows that silently re-attach the stock catalog.
• Indexes — the repository definition travels, the built segments do not (copying them yields 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 don't survive a deserialize (logo width is the canary), and IsDryRun before every hosted deserialize.
• Orders ride a plain SqlTable predicate, though no shipped example config includes them.

Corrections to existing guidance

Was	Now
Upload never overwrites → delete before re-uploading	allowOverwrite=true — an undocumented form field that works. Success is model being a list, never status: ok: a refused batch reports ok, writes nothing, and one pre-existing name drops the batch's new files too.
"A cloud install CAN be restarted"	Qualified. The CloudHosting control files are a Dynamicweb Cloud affordance. A partner-hosted install accepted recycle.txt/restart.txt and never acted on them — confirm the file is consumed, or rung 3 doesn't exist on that host.
serializer-reference.md: "mode": "Deploy"|"Seed" is the current enum	Version-scoped. 0.8.x accepts only Replace/Merge — Deploy/Seed are rejected, not aliased (ConfigLoader.ValidatePredicates) — and the run's mode moves into the JSON body. 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 the prescribed one-call config-validity probe.

deserialize-flow.md's 0.6.9-stamped two-pass ?mode= flow is still correct for 0.6.9 and gains a pointer for 0.8.x callers.

Gates

• python scripts/validate-skills.py → 0 errors, 0 warnings
• Sanitization grep pack (engagement tokens / session-relative time / customer paths) → clean across the staged diff and the commit message
• Supersede sweep run across skills/ for the Deploy/Seed claim — three hits, all resolved (one was already correct, one corrected, one version-pointed)
• metadata.version 4.8.0 → 4.9.0 (minor — new reference), README + CHANGELOG updated in the same commit