Add dw-demo-headless skill: Next.js storefront + DW10 Delivery API demos

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude skills for Dynamicweb 10 — organized by task domain, bundled by role.",
-    "version": "3.8.6"
+    "version": "3.9.0"
   },
   "plugins": [
     {
@@ -87,6 +87,7 @@
         "./skills/dw-demo-base",
         "./skills/dw-demo-pim",
         "./skills/dw-demo-swift",
+        "./skills/dw-demo-headless",
         "./skills/dw-demo-erp",
         "./skills/dw-integration-bc",
         "./skills/dw-integration-framework",

CHANGELOG.md

@@ -3,6 +3,39 @@
 All notable changes to the Dynamicweb Skills plugin are recorded here. The
 `version` field in `.claude-plugin/marketplace.json` tracks these entries.
 
+## [3.9.0]
+
+### Added
+- **New skill `dw-demo-headless` — headless-commerce demos (Next.js storefront + DW10 Delivery
+  API).** A new `flow` demo skill in the presales cluster, sister to `dw-demo-swift` and
+  "Use AFTER `dw-demo-base`", covering the fifth demo consumer: a `vercel/commerce`-based Next.js
+  storefront driven by the Dynamicweb 10 Delivery API (`/dwapi/**`) over a dedicated,
+  presentation-agnostic serialized baseline that is its own product line — fully decoupled from
+  Swift, sharing no item-type rows. Three references:
+  - `references/headless-backend.md` — configure/verify the DW10 backend for headless: the Delivery
+    API surface map (endpoint/auth table; REST/JSON only, no GraphQL/OData), the **two-token trap**
+    (the admin/Management token 401s on `/dwapi`; the frontend needs a JWT from
+    `POST /dwapi/users/authenticate {UserName,Password}` → `{token}`), the locale gotcha (product
+    data lives under `ENU`, not `LANG1` — always pass `LanguageId`+`ShopId`), the PLP
+    repository/named-query requirement (`GET /dwapi/ecommerce/products/search?RepositoryName=…&QueryName=…`;
+    `POST /dwapi/ecommerce/products` 400s — count at `totalProductsCount`, facets at
+    `facetGroups[i].facets[j]`), and the item-type-XML-materialized-at-startup fact.
+  - `references/headless-frontend.md` — work with the Next.js storefront: the provider-module
+    data-layer swap (replace `lib/shopify/` with `lib/dynamicweb/`, keep every UI component), `DW_*`
+    env wiring, the self-signed-TLS dev bypass (`NODE_TLS_REJECT_UNAUTHORIZED=0`, dev-only), the
+    build-time RSC fetch caveat (`next build` needs a reachable provider), slug conventions (product
+    number = handle; group id = collection handle), and `@vercel/*` self-host disposition.
+  - `references/headless-baseline.md` — deserialize the headless baseline: the `Headless_*`
+    presentation-agnostic item-type layer, the `200000–209999` id floor band (an authoring
+    convention verified in YAML — DW reassigns DB ids), EN/NL sibling-area parity (paired manifest
+    entries), disk-overlay staging of `itemtypes/` + `repositories/` BEFORE host start, and the Full
+    index build after deserialize.
+  Registered the skill in `.claude-plugin/marketplace.json` (dynamicweb-presales plugin) and
+  regenerated `manifest.json`. Added the headless demo path to `dw-demo-base` SKILL.md (sister-skill
+  list + the baseline "explicit non-step") so it is discoverable from the foundation skill. Routes
+  to the existing `dw-headless-delivery` knowledge skill for the raw endpoint catalog rather than
+  duplicating it.
+
 ## [3.8.6]
 
 ### Fixed

manifest.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-07-01T22:46:05.923Z",
+  "generatedAt": "2026-07-03T07:52:43.546Z",
   "skills": [
     {
       "name": "dw-demo-base",
@@ -16,6 +16,13 @@
       "description": "Dynamicweb 10 ERP integration -- owns the always-on rule that an ERP is a source AND target in DW10's Integration Framework, never a `ShopType=3` channel or an `EcomFeed`.",
       "path": "skills/dw-demo-erp/SKILL.md"
     },
+    {
+      "name": "dw-demo-headless",
+      "type": "flow",
+      "group": "demo",
+      "description": "Dynamicweb 10 headless-commerce demos — a Next.js storefront (vercel/commerce starter) driven by the DW10 Delivery API, plus a dedicated presentation-agnostic serialized baseline.",
+      "path": "skills/dw-demo-headless/SKILL.md"
+    },
     {
       "name": "dw-demo-pim",
       "type": "flow",

skills/dw-demo-base/SKILL.md

@@ -2,7 +2,7 @@
 name: dw-demo-base
 type: flow
 group: demo
-description: Foundation skill for Dynamicweb 10 demos — scaffolds the dw10-suite host, wires Backend MCP and the localhost TLS bypass, and drops the customisations and customer-context guardrails. Does NOT load a baseline. Use FIRST on any new Dynamicweb demo, when MCP tools fail to load ("Failed to connect", silent tools/list), on a fresh Windows machine, when auditing the customisation budget, or when the demo targets a hosted/cloud install reached only by URL + Admin API key (references/online-mode.md). Also owns the orchestrator abstraction (GSD primary vs the native `/demo:*` commands) — "drive the demo build", "run the demo natively", "GSD vs native" route to references/orchestrator.md — and the maintainer fold-back workflow — "fold this into the skill", "save this back to the plugin" route to references/iterate-plugin.md. Sister skills (dw-demo-pim, dw-demo-swift, dw-demo-erp, dw-integration-bc) are Use AFTER, never standalone. `<demo>\customer-context\` is read-only.
+description: Foundation skill for Dynamicweb 10 demos — scaffolds the dw10-suite host, wires Backend MCP and the localhost TLS bypass, and drops the customisations and customer-context guardrails. Does NOT load a baseline. Use FIRST on any new Dynamicweb demo, when MCP tools fail to load ("Failed to connect", silent tools/list), on a fresh Windows machine, when auditing the customisation budget, or when the demo targets a hosted/cloud install reached only by URL + Admin API key (references/online-mode.md). Also owns the orchestrator abstraction (GSD primary vs the native `/demo:*` commands) — "drive the demo build", "run the demo natively", "GSD vs native" route to references/orchestrator.md — and the maintainer fold-back workflow — "fold this into the skill", "save this back to the plugin" route to references/iterate-plugin.md. Sister skills (dw-demo-pim, dw-demo-swift, dw-demo-headless, dw-demo-erp, dw-integration-bc) are Use AFTER, never standalone. `<demo>\customer-context\` is read-only.
 ---
 
 # Dynamicweb Demo Base Skill
@@ -50,12 +50,13 @@ Walk every step in order — skip none. Each step's reference contains its own v
 
 ## Baseline data — explicit non-step
 
-Loading reference content into the project DB is **NOT** part of this skill's canonical flow. Two separate paths follow base, depending on demo type:
+Loading reference content into the project DB is **NOT** part of this skill's canonical flow. Three separate paths follow base, depending on demo type:
 
 - **PIM demo** -> start with a blank/fresh demo DB; the PIM skill's modelling recipes build content from scratch via MCP. No deserialize step. See [`dynamicweb-pim-demo/SKILL.md`](../dw-demo-pim/SKILL.md).
-- **Swift demo** -> deserialize the Swift content baseline from `$env:DW_VAULT\serialized-data\<baseline>\` via the Serializer. Owned end-to-end by [`dynamicweb-swift-demo/references/deserialize-flow.md`](../dw-demo-swift/references/deserialize-flow.md) + [`dynamicweb-swift-demo/references/integrity-sweep.md`](../dw-demo-swift/references/integrity-sweep.md). Prerequisite: the Serializer is installed per [`references/serializer-reference.md`](references/serializer-reference.md) "Installation".
+- **Swift demo** -> deserialize the Swift content baseline via the Serializer. Owned end-to-end by [`dynamicweb-swift-demo/references/deserialize-flow.md`](../dw-demo-swift/references/deserialize-flow.md) + [`dynamicweb-swift-demo/references/integrity-sweep.md`](../dw-demo-swift/references/integrity-sweep.md). Prerequisite: the Serializer is installed per [`references/serializer-reference.md`](references/serializer-reference.md) "Installation".
+- **Headless demo** -> deserialize the separate, presentation-agnostic `headless/2.3` baseline (its own product line, no shared item-type rows with Swift) for a Next.js storefront that reads the DW10 Delivery API. Owned by [`dynamicweb-headless-demo/references/headless-baseline.md`](../dw-demo-headless/references/headless-baseline.md); backend config in [`headless-backend.md`](../dw-demo-headless/references/headless-backend.md). Same Serializer prerequisite.
 
-The Serializer install steps live in base so any sister skill can pull them; the act of deserializing is Swift-specific.
+The Serializer install steps live in base so any sister skill can pull them; the act of deserializing is Swift- or headless-specific.
 
 ## Where to find things
 

skills/dw-demo-headless/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: dw-demo-headless
+type: flow
+group: demo
+description: Dynamicweb 10 headless-commerce demos — a Next.js storefront (vercel/commerce starter) driven by the DW10 Delivery API, plus a dedicated presentation-agnostic serialized baseline. Triggers: building a headless/decoupled storefront demo, wiring a Next.js/vercel-commerce frontend to a DW10 backend, "the /dwapi call returns 401 with my admin token", product search returns 400 on POST /dwapi/ecommerce/products, PLP needs a repository+query, product data missing under a language, deserializing a headless baseline, Headless_* item types, running/building the storefront against a self-signed dev host. Non-triggers: server-side Swift storefront -> dw-demo-swift; PIM data modelling -> dw-demo-pim; raw Delivery API endpoint catalog (non-demo) -> dw-headless-delivery; demo setup/MCP/TLS -> dw-demo-base. Use AFTER dw-demo-base (host running, Serializer installed). Headless is its own baseline product line, fully decoupled from Swift.
+---
+
+# Dynamicweb Headless Demo Skill
+
+Build a **headless-commerce demo**: a Next.js storefront (from the `vercel/commerce`
+starter) that reads a Dynamicweb 10 backend through the **Delivery API** (`/dwapi/**`), backed
+by a **dedicated, presentation-agnostic serialized baseline** that is its own product line —
+fully decoupled from the Swift baseline. **Use AFTER** `dynamicweb-demo-base` — assumes a host
+is running, TLS bypass is wired, and the Serializer is installed in the host (per base's
+[`../dw-demo-base/references/serializer-reference.md`](../dw-demo-base/references/serializer-reference.md)
+"Installation").
+
+This SKILL.md is pure nav. Headless is a knowledge book, not a recipe — see references for any
+specific topic.
+
+## How to run me
+
+This skill holds domain knowledge, not build sequencing. An **orchestrator** owns the phase
+order: GSD injects this skill into its agents (via the `agent_skills` block), or the native
+`/demo:*` command set invokes it; **standalone**, the skill's own lightweight harness guards its
+documented order (gate every step, persist progress to `.demo/<slug>/flow-state.json`). The
+orchestrator abstraction (GSD primary, native command set, and the standalone harness) is owned by
+[`../dw-demo-base/references/orchestrator.md`](../dw-demo-base/references/orchestrator.md).
+
+## Headless vs Swift — pick the right demo flow
+
+A headless demo and a Swift demo are **separate product lines**, not two skins of one baseline:
+
+- **Swift demo** (`dynamicweb-swift-demo`) — DW renders the storefront server-side with Razor;
+  content is presentation-coupled (`Swift-v2_*` paragraph item types carry template/layout/
+  colorscheme/icon fields). Loads the `swift-2.3` baseline.
+- **Headless demo** (this skill) — a **separate** Next.js app renders the storefront; DW is a pure
+  JSON backend behind `/dwapi/**`. Content is presentation-agnostic (`Headless_*` item types carry
+  no layout fields). Loads a **separate** `headless/2.3` baseline that shares **no** item-type rows
+  with Swift.
+
+Do not port Swift paragraph item types into a headless demo — that reintroduces the presentation
+coupling headless exists to avoid. Reuse the commerce/PIM **domain** model (products, groups,
+variants, prices, orders, users, facets — all delivered through the Delivery API, never as item
+types) and field-type conventions only.
+
+## Step 0 — Stand up the headless demo (every headless demo)
+
+Walk these in order; each reference owns its own verification gate.
+
+1. **Configure and verify the DW10 backend for headless** -> [`references/headless-backend.md`](references/headless-backend.md)
+   Confirm the Delivery API (`/dwapi/**`) is reachable, learn the endpoint/auth surface map, and
+   clear the **two-token trap** (the admin/Management token 401s on `/dwapi`; the frontend needs a
+   JWT from `POST /dwapi/users/authenticate`). Owns the locale gotcha (product data lives under
+   `ENU`, not `LANG1` — always pass `LanguageId`+`ShopId`) and the PLP repository/named-query
+   requirement (search is `GET /dwapi/ecommerce/products/search?RepositoryName=…&QueryName=…`;
+   `POST /dwapi/ecommerce/products` 400s).
+
+2. **Deserialize the headless baseline** -> [`references/headless-baseline.md`](references/headless-baseline.md)
+   Stage the disk-overlay `itemtypes/` and `repositories/` **before** host start (DW materializes
+   item types and repositories at startup), deserialize the `deploy/` then `seed/` mode trees, and
+   run a **Full** index build afterwards. Owns the `Headless_*` item-type layer, the id floor band,
+   and EN/NL sibling-area parity.
+
+3. **Wire and run the Next.js storefront** -> [`references/headless-frontend.md`](references/headless-frontend.md)
+   Swap the starter's default provider for a DynamicWeb data-layer module, wire the `DW_*` env vars,
+   apply the self-signed-TLS dev bypass, and run/build it against the backend. Owns the slug
+   conventions (product number = handle; group id = collection handle) and the build-time RSC fetch
+   caveat (the starter cannot `next build` without a reachable provider).
+
+## Where to find things
+
+| If you need to... | Read this reference |
+|---|---|
+| **Configure/verify the DW10 backend for headless** — Delivery API surface map + auth model, the two-token trap, the ENU/ShopId locale gotcha, the PLP repository+query requirement, item-type XML materialization | **references/headless-backend.md** |
+| **Deserialize the headless baseline** — `Headless_*` item-type layer, id floor band, EN/NL parity, disk-overlay staging of `itemtypes/`+`repositories/` before host start, Full index build after deserialize | **references/headless-baseline.md** |
+| **Work with the Next.js storefront** — provider-module/data-layer swap, `DW_*` env wiring, self-signed-TLS dev bypass, build-time RSC fetch caveat, slug conventions | **references/headless-frontend.md** |
+| **The raw Delivery API endpoint catalog** (non-demo reference — content/commerce/users/forms/query families, request/response shapes) | [`../dw-headless-delivery/SKILL.md`](../dw-headless-delivery/SKILL.md) |
+| **Build a per-demo product search index** by hand (Lucene `ProductIndexBuilder`, query + facets) | [`../dw-search-indexing/SKILL.md`](../dw-search-indexing/SKILL.md) |
+
+## Inherited from dynamicweb-demo-base
+
+This skill assumes `dynamicweb-demo-base` ran first. Its always-on rules are NOT restated here —
+see the owning reference in base for each:
+
+| Rule | Owner |
+|------|-------|
+| Customer-context read-only contract | [dynamicweb-demo-base/references/customer-context.md](../dw-demo-base/references/customer-context.md) |
+| Customisations-ledger preflight | [dynamicweb-demo-base/references/customisations.md](../dw-demo-base/references/customisations.md) |
+| Baseline-drift self-diagnosis rule | [dynamicweb-demo-base/SKILL.md "Self-diagnosis rule"](../dw-demo-base/SKILL.md) |
+
+If you find yourself running this skill standalone with no base context, fix that before
+continuing — see the description's "Use AFTER" hint. If `dynamicweb-demo-base` is not installed,
+install it first — this skill's inherited rules require it.
+
+## Sister skills
+
+- **`dynamicweb-demo-base`** — foundation skill (Use FIRST). Owns all setup + Serializer install +
+  customisations + customer-context. Does NOT deserialize a baseline.
+- **`dynamicweb-swift-demo`** — the Swift (server-side Razor) storefront line. A headless demo is
+  the decoupled peer of a Swift demo, not a variant of it; the two baselines never share item-type
+  rows.
+- **`dynamicweb-pim-demo`** — PIM modelling from a blank DB. The headless baseline reuses the same
+  commerce/PIM domain model PIM builds; pair them when a headless demo needs richer catalog data.
+- **`dynamicweb-headless-delivery`** — the raw `/dwapi/` knowledge skill (endpoint catalog, auth,
+  architecture rules). This demo skill routes to it for endpoint detail rather than duplicating it.