@se-studio/contentful-cms 3.10.0 → 3.10.2

package/dist/session/refs.js.map

@@ -1 +1 @@
-{"version":3,"file":"refs.js","sourceRoot":"","sources":["../../src/session/refs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../../src/session/refs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAGpE;;;GAGG;AACH,SAAS,YAAY,CAAC,OAAqB,EAAE,GAAW;IACtD,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;IACrD,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACvB,OAAO,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;IAC3D,CAAC;IACD,IACE,MAAM,KAAK,KAAK;QAChB,CAAC,OAAO,CAAC,aAAa,KAAK,MAAM,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,EACzE,CAAC;QACD,OAAO,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;IAC3D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,OAAqB,EAAE,GAAW;IAC3D,MAAM,aAAa,GAAG,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvD,MAAM,QAAQ,GACZ,OAAO,CAAC,aAAa,KAAK,MAAM,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS;YACrE,CAAC,CAAC,gDAAgD;YAClD,CAAC,CAAC,gDAAgD,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,QAAQ,aAAa,gCAAgC,SAAS,IAAI,QAAQ,EAAE,CAAC,CAAC;IAChG,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,UAAU,OAAO,yDAAyD,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAAqB,EAAE,GAAW;IAC/D,MAAM,aAAa,GAAG,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,QAAQ,aAAa,gCAAgC,SAAS,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAqB,EAAE,GAAW;IAC7D,MAAM,aAAa,GAAG,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACjD,OAAO,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,aAAa,CAAC,IAAI,IAAI,CAAC;AACxE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,WAAmB,EACnB,OAAwC,EACxC,MAAc;IAEd,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,MAAM,WAAW,GAA2B,EAAE,CAAC;IAC/C,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,SAAS,SAAS,CAAC,OAAe;QAChC,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,GAAG,GAAG,KAAK,OAAO,EAAE,EAAE,CAAC;QAC7B,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;QACpB,WAAW,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC;QAC3B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,SAAS,QAAQ,CACf,OAAe,EACf,QAAuB,EACvB,WAA0B,EAC1B,KAAa;QAEb,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK;YAAE,OAAO;QAEnB,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;QAC/B,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;QAE/D,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,cAAc,GAClB,IAAI,KAAK,YAAY;YACnB,CAAC,CAAC,CAAC,UAAU,CAAC;YACd,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,SAAS;gBACrC,CAAC,CAAC,CAAC,YAAY,EAAE,SAAS,EAAE,eAAe,CAAC;gBAC5C,CAAC,CAAC,IAAI,KAAK,UAAU;oBACnB,CAAC,CAAC,CAAC,YAAY,EAAE,aAAa,CAAC;oBAC/B,CAAC,CAAC,IAAI,KAAK,YAAY;wBACrB,CAAC,CAAC,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC;wBACxC,CAAC,CAAC,EAAE,CAAC;QAEf,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;YACrC,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACxC,IAAI,CAAC,SAAS;gBAAE,SAAS;YACzB,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC;YACtD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAAE,SAAS;YAEpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;oBACtB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC5B,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;wBACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;oBACjD,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACrC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,SAAS,uBAAuB,CAAC,KAAsB,EAAE,MAAc;IACrE,MAAM,IAAI,GAAG,2BAA2B,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACxD,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CACzC,KAAsB,EACtB,MAAc,EACd,cAAoC;IAEpC,OAAO,0BAA0B,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAC1E,CAAC;AAED,SAAS,WAAW,CAAC,IAAa;IAChC,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,KAAK,IAAI,IAAI;QACb,OAAQ,IAAyB,CAAC,GAAG,KAAK,QAAQ;QACjD,IAAuC,CAAC,GAAG,CAAC,QAAQ,KAAK,OAAO,CAClE,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAG3C,OAAO,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC;AACnE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAG3C,OAAO,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC;AACnE,CAAC"}

package/docs/editor-tasks/create-from-document.md

@@ -16,7 +16,7 @@
 
 - Fetch package materials (Google Drive MCP, paste, Figma link, zip, production ref, **or designer HTML**)
 - Read `cms-edit://customer/components-index`, `routing`, and for articles **`articles`**
-- **Designer HTML / interactive prototype:** if `cms-edit://customer/task-create-html-component` (or another site HtmlComponent playbook) exists, **switch to that playbook** and stop this one. Otherwise follow the HtmlComponent fork in Phase 2 — do not flatten custom CSS/JS/scroll into registered cards.
+- **Designer HTML / interactive prototype / vendor JS:** switch to `cms-edit://customer/task-create-html-component` and stop this one. Do not flatten custom CSS/JS/scroll into registered cards. Libraries go on `externalScripts`, never `<script src>` or `createElement('script')`.
 - **Non-trivial packages:** complete **`task-source-readiness-review`** first (inventory → beat sheet → verdict → light human yes)
 
 ## Steps
@@ -44,7 +44,7 @@
    - If the source is custom HTML/JS, sticky/scroll, diagrams, or a private layout shell, and this space has `htmlComponent`, map that beat to **`htmlComponent`** — not cards/lists that only match the copy.
    - Mixed pages are expected. Merge consecutive custom sections that share CSS/JS/sticky into **one** HtmlComponent. Do not emit one HtmlComponent per `<section>`.
    - Prefer **source order** over CMS convenience (do not invent side-by-side pairs unless the source is a true pair).
-3. **Propose plan** (can reuse the soft-proof): slug, title, template/article type, ordered component list (registered **and** `htmlComponent` where needed), gap/placeholder list, **asset map** — **ask user to confirm** with a light **yes** if not already confirmed. For HtmlComponent beats: extract `data:` media first; run `schema htmlComponent` for this space’s field IDs (`html` vs `htmlContent`).
+3. **Propose plan** (can reuse the soft-proof): slug, title, template/article type, ordered component list (registered **and** `htmlComponent` where needed), gap/placeholder list, **asset map** — **ask user to confirm** with a light **yes** if not already confirmed. For HtmlComponent beats: extract `data:` media first; run `schema htmlComponent` for this space’s field IDs (`html` vs `htmlContent`); list vendor URLs for `externalScripts` (see `task-create-html-component`).
 4. For pages: `list --type template` — pick template; check template `preContent` / `postContent` so heroes are not duplicated.
 5. For articles: resolve `articleType`; apply site SEO and lab rules from `articles` playbook.
 6. Build `create from-json` payload **or** prefer incremental `open` → `add` / `set` / `rtf` for large multi-block work. Link visuals using the pack map from Phase 1.
@@ -81,4 +81,4 @@ Use MCP prompts `cms_edit_create_from_doc` or `cms_edit_create_article_from_doc`
 - `task-create-page`
 - `task-media-reuse-and-upload`
 - `task-preview-verify`
-- Site HtmlComponent playbook when present (`cms-edit://customer/task-create-html-component`)
+- `cms-edit://customer/task-create-html-component`

package/docs/editor-tasks/create-html-component.md

@@ -0,0 +1,135 @@
+# Capability: Create from designer HTML (HtmlComponent)
+
+## Intent phrases
+
+- build from designer HTML
+- HTML dump
+- create from HTML prototype
+- import HTML landing page
+- HtmlComponent from HTML
+- custom HTML page
+- load HtmlComponent external scripts
+
+## Requires capabilities
+
+`pages` or `articles`
+
+## Prerequisites
+
+- Read `cms-edit://customer/pages` (or `articles`) and `cms-edit://customer/components-index`
+- `cms_edit ["schema", "htmlComponent"]` — use this space’s field IDs (`rawHtml` vs `htmlContent`, `customJs` vs `jsContent`). **`externalScripts` is the same field id on every space.**
+- Designer HTML / prototype available (file, paste, or Drive). **Do not** paste a multi-megabyte dump with `data:` URIs into Contentful.
+- For ordinary Google Doc / Figma-to-registered-stack briefs with no custom CSS/JS, use `task-create-from-document` instead.
+
+## When to use this playbook
+
+Use this when the source is a **designer HTML dump**, interactive prototype, or a block that needs a **third-party JS library**. Do not flatten custom CSS/JS/scroll into registered cards because the copy looks like a card grid.
+
+## Per-section decision
+
+For **each** source section, ask: do **layout and interaction** match a registered type?
+
+| Fit | Action |
+|-----|--------|
+| Strong (same pattern) | Use the registered type. |
+| Medium (copy matches, chrome differs) | Ask the human: site chrome vs keep HtmlComponent. |
+| Weak / none | HtmlComponent. Custom sticky scroll, diagrams, widgets, vendor JS. |
+
+Mock **nav and footer** in the HTML: strip. The page **template** supplies chrome.
+
+## Split HtmlComponents (mixed pages)
+
+Mixed pages are expected: registered types **plus** one or more `htmlComponent` entries.
+
+**Do split** when a section matches a registered type, remaining HTML would exceed field limits, or adjacent custom blocks **do not share** JS/CSS/sticky state.
+
+**Do not split** when one behaviour spans the markup (sticky rail + stacked cards) or several sections share one stylesheet / SVG sprite / library.
+
+Rules:
+
+1. Registered match → registered type.
+2. Merge consecutive custom sections that share CSS/JS into **one** HtmlComponent.
+3. Start a new HtmlComponent only at a clean boundary (no shared script, no sticky parent).
+4. Never one HtmlComponent per `<section>` by default.
+
+## External scripts (non-negotiable)
+
+Put third-party libraries in **`externalScripts`**, not `<script src>` in HTML and not `createElement('script')` inside `customJs`.
+
+Allowed values:
+
+- Same-origin paths under `/html-components/` that end in `.js` (no `..`, no query, no hash). Prefer files in the site repo at `public/html-components/<feature>/….js`.
+- HTTPS URLs whose hostname is already listed on the site’s `CmsRendererConfig.htmlComponentExternalScriptHosts`. If the site sets CSP, that host must also be in `script-src`.
+
+If the host is **not** allowlisted, **stop** — do not invent a CDN load and do not patch renderer config without a human.
+
+Rejected (renderer drops these; preview/dev may warn): `http:`, `javascript:`, protocol-relative `//…`, path `..`, query/hash on same-origin paths.
+
+Max **10** URLs per entry. Duplicate URLs on one page share one `next/script` id. Externals load with `scriptStrategy` (default `afterInteractive`). **`customJs` runs only after every listed src is ready**; if any src fails, inline JS is not injected.
+
+### How to set `externalScripts`
+
+It is an **Array of Symbol**, not a string. Scalar `set` is rejected.
+
+```text
+cms_edit ["set", "@cN", "externalScripts", "--json", "[\"/html-components/feature/lib.js\"]"]
+```
+
+On `create from-json`, put the same array under `fields.externalScripts`. Run `schema htmlComponent` first — unknown keys fail (`html` vs `htmlContent`).
+
+Then set HTML/CSS/JS with `--content` / `--content-base64` on `rawHtml`/`customCss`/`customJs` (or this space’s dual-write ids).
+
+## Media first (mandatory)
+
+1. Extract binary media from `data:` URIs and local files. Upload via `task-media-reuse-and-upload` (search/reuse first).
+2. Rewrite HTML `src` / `poster` to Contentful or CDN URLs. Never leave base64 in the field.
+3. `markdownContent` = user-visible copy and structure. Omit layout chrome and JS behaviour.
+
+## HtmlComponent authoring
+
+1. Follow the site HTML style guide (`docs/cms-guidelines/html-component-style-guide.md` when available).
+2. Scope all JS queries to injected `hcRoot`.
+3. `isHero` — `true` if this block contains the page `<h1>`. `fullWidth` — as needed for full-bleed sections.
+4. Set `cmsLabel` immediately (never leave “New Generic”).
+5. Dual-write legacy + core field IDs when `schema htmlComponent` shows both.
+6. Draft only — never publish unless the human explicitly asks.
+
+## Steps
+
+1. Inventory sections. For each: registered / ask / HtmlComponent. Merge custom blocks that share CSS/JS.
+2. List vendor libraries. Copy same-origin files into `public/html-components/<feature>/` or confirm the HTTPS host is already allowlisted.
+3. Post a soft-proof (ordered stack + `externalScripts` URLs) and get a light human **yes**.
+4. Media pipeline: extract, upload, rewrite URLs.
+5. Create or open the page/article. Add registered components where decided.
+6. For each HtmlComponent: `add htmlComponent` (or `create from-json --dry-run --strict` with this space’s field keys).
+7. Set `externalScripts` with `--json`. Set HTML/CSS/JS. Set `cmsLabel`.
+8. `diff` → `save` (draft).
+9. `cms_edit ["preview", "urls", "<slug>"]` — follow `task-preview-verify`. Confirm libraries load (no `createElement('script')`, no dropped-URL warnings).
+
+## Confirmation gates
+
+1. Soft-proof (mixed stack + script URLs) + human yes
+2. Media extracted (no `data:` in saved HTML)
+3. `schema htmlComponent` field IDs used
+4. Libraries only via `externalScripts`
+5. `diff` before `save`
+
+## Out of scope
+
+- Publish
+- Flattening custom interaction into cards/lists because copy looks similar
+- One HtmlComponent per `<section>` by default
+- Rewriting source copy
+- Pasting the raw designer file into HTML
+- Adding a new CDN host to `htmlComponentExternalScriptHosts` without a human
+- Scalar `set` of a single URL string onto `externalScripts`
+
+## Related resources
+
+- `cms-edit://customer/pages`
+- `cms-edit://customer/task-create-from-document`
+- `cms-edit://customer/task-create-page`
+- `cms-edit://customer/task-media-reuse-and-upload`
+- `cms-edit://customer/task-preview-verify`
+- `cms-edit://customer/task-publish-handoff`
+- `cms_edit ["help", "fields-html-component"]`

package/docs/editor-tasks/navigation.md

@@ -18,16 +18,21 @@
 ## Steps
 
 1. `cms_edit ["list", "--type", "navigation"]` — find nav entry
-2. `cms_edit ["nav", "open", "--id", "<navigationId>"]` or by slug
-3. `snapshot` — inspect nav items
-4. Add/clone/link items per navigation commands
-5. `diff` → `save`
+2. `cms_edit ["nav", "open", "--nav-id", "<navigationId>"]` or `["nav", "open", "--nav-name", "Main menu"]` — **not** `--id`
+3. `snapshot` — inspect nav items (array field may be `entries`, `items`, or `navigationItems`)
+4. **Ask** whether the change is **global** (template `menu`) or **page-specific** (`page.menu` override). Nested children (often the last header CTA) are usually **shared**.
+   - Global: `set` on the existing NavigationItem
+   - Page-specific: new NavigationItem + cloned/new menu, then `set` `page.menu` — do not mutate the shared item
+5. Add/clone/link items per navigation commands. `nav clone` is **shallow** for nested `navigationItems`.
+6. `diff` → `save`
+
+`peek` is one-shot. `open` / `nav open` persist. `preview urls /slug` follows that slug even if session `_mcp` is another page.
 
 See `contentful-cms-navigation` skill for full command reference in dev environments.
 
 ## Confirmation gates
 
-1. Confirm which menu (header/footer) and link changes
+1. Confirm which menu (header/footer) and whether the edit is global vs this page
 2. `diff` before `save`
 
 ## Out of scope
@@ -36,4 +41,4 @@ See `contentful-cms-navigation` skill for full command reference in dev environm
 
 ## Related resources
 
-- `cms-edit://customer/routing`
+- `cms-edit://customer/routing`

package/docs/editor-tasks/source-readiness-review.md

@@ -45,11 +45,11 @@ If title, order, or hero asset **conflict** and the user has not decided → **N
    |---|------|-------------------|-----------------------------------|----------------------|
    | 1 | … | … | … | … |
 
-3. **Build beat sheet** — ordered narrative + visual beats. For each beat: use a **registered** component/collection type when **layout and interaction** match (`components-index` / site playbook). If the source is designer HTML, custom CSS/JS, sticky/scroll, or a diagram that no registered type can reproduce, map to **`htmlComponent`** when that type exists in the space (and follow a site `task-create-html-component` playbook if present). Mixed stacks are valid. Merge consecutive custom HTML beats that share CSS/JS. Prefer **source order** over CMS convenience.
+3. **Build beat sheet** — ordered narrative + visual beats. For each beat: use a **registered** component/collection type when **layout and interaction** match (`components-index` / site playbook). If the source is designer HTML, custom CSS/JS, sticky/scroll, or a diagram that no registered type can reproduce, map to **`htmlComponent`** when that type exists in the space and follow **`task-create-html-component`**. Mixed stacks are valid. Merge consecutive custom HTML beats that share CSS/JS. Prefer **source order** over CMS convenience. Vendor libraries belong on `externalScripts`.
 4. **Score verdict** using the threshold below.
 5. **Post one-screen soft-proof** — numbered final `content` (or page stack) order + gap list + verdict.
 6. **Ask for a light human confirm** — accept **yes** / **go** / **proceed** (or equivalent). Do not build on silence if the package is non-trivial.
-7. On **GO** or **GO-WITH-GAPS** + yes → hand off to `task-create-html-component` (if the site has it and the source is designer HTML), otherwise `task-create-from-document` / `task-create-article` / `task-create-page` with the soft-proof as the plan.
+7. On **GO** or **GO-WITH-GAPS** + yes → hand off to `task-create-html-component` when the source is designer HTML / vendor JS, otherwise `task-create-from-document` / `task-create-article` / `task-create-page` with the soft-proof as the plan.
 8. On **NO-GO** → stop; list what is blocking (do not invent structure to unblock).
 
 ## Gap threshold
@@ -114,4 +114,4 @@ Copy: unchanged from source (list any human decisions only)
 - `task-media-pipeline-prepare`
 - `task-media-reuse-and-upload`
 - `task-preview-verify`
-- Site `task-create-html-component` when present
+- `task-create-html-component`

package/docs/help/create-from-json.md

@@ -17,7 +17,7 @@ cms_edit ["create", "from-json", "--json", "{...}", "--dry-run", "--strict"]
 - Nested tree key is **`components`**, not `content` (`content` is a page field — empty page).
 - Discriminator is **`type`**, not `componentType` / `collectionType`.
 - **`components` must be non-empty**.
-- Unknown nested keys fail (`html` vs `htmlContent` — run `schema htmlComponent` for this space).
+- Unknown nested keys fail (`html` vs `htmlContent` — run `schema htmlComponent` for this space). Put vendor libraries on `fields.externalScripts` (string array), not inside HTML.
 - CTA text is **`label`**, not `linkText`.
 - Quoted `set @c1:field="value"` is rejected (quotes would be stored). Use `["set", "@c1", "field", "value"]`.
 
@@ -403,3 +403,29 @@ Once created:
 3. Publish in the Contentful web app when ready.
 
 The tool prints the Contentful web app URL for the new entry after creation.
+
+---
+
+## HtmlComponent example
+
+Run `schema htmlComponent` first. Field ids below are the core names; some spaces use `htmlContent` / `cssContent` / `jsContent` instead (or dual-write both). Vendor libraries belong on `externalScripts`, not inside HTML.
+
+```json
+{
+  "type": "page",
+  "slug": "/lab/html-widget",
+  "title": "HTML widget",
+  "components": [
+    {
+      "contentType": "htmlComponent",
+      "cmsLabel": "Widget — jsPDF demo",
+      "fields": {
+        "rawHtml": "<div class=\"widget\"><button type=\"button\" class=\"export\">Export</button></div>",
+        "customJs": "hcRoot.querySelector('.export').addEventListener('click', function () { window.jspdf.jsPDF(); });",
+        "externalScripts": ["/html-components/widget/jspdf.umd.min.js"],
+        "markdownContent": "Export widget"
+      }
+    }
+  ]
+}
+```

package/docs/help/fields-html-component.md

@@ -0,0 +1,78 @@
+# cms-edit — HtmlComponent Field Reference
+
+An `htmlComponent` entry is developer-authored HTML, optional scoped CSS, optional inline JS, and optional **external script URLs**. It is not a registered `component` variant.
+
+Run `cms-edit schema htmlComponent` for this space’s field IDs. Some spaces dual-write legacy names (`htmlContent` / `cssContent` / `jsContent`) plus core ids (`rawHtml` / `customCss` / `customJs`). **`externalScripts` is the same id on every space.** Unknown JSON keys fail (`html` vs `htmlContent`).
+
+See `cms-edit://customer/task-create-html-component` for the full create playbook.
+
+---
+
+## Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `cmsLabel` | Symbol | Yes | Internal label. Set immediately. |
+| `rawHtml` / `htmlContent` | Text | Yes | Markup. No `<script src>`. |
+| `customCss` / `cssContent` | Text | No | Auto-scoped to `[data-hc-id]`. |
+| `customJs` / `jsContent` | Text | No | Inline JS via `next/script`. Scope queries to injected `hcRoot`. |
+| `externalScripts` | Array of Symbol | No | Allowlisted script URLs loaded **before** `customJs`. Max 10. |
+| `markdownContent` | Text | No | Plain text for search / markdown export. |
+| `scriptStrategy` | Symbol | No | `afterInteractive` (default), `lazyOnload`, `beforeInteractive`. Applies to externals and inline JS. |
+| `isHero` | Boolean | No | `true` when the HTML contains the page `<h1>`. |
+| `fullWidth` | Boolean | No | Viewport-breakout layout when the site renderer supports it. |
+| `excludeFromSearch` | Boolean | No | Skip search even if `markdownContent` is set. |
+| `loadScriptOnce` | Boolean | No | Dedupe inline script id per entry (default true). External URLs already share one `next/script` id per URL. |
+
+---
+
+## `externalScripts` allowlist
+
+Always allowed: same-origin paths matching `/html-components/` + a `.js` filename (no `..`, no query, no hash). Prefer files in the site repo at `public/html-components/<feature>/….js`.
+
+HTTPS URLs are allowed only when the hostname is in `CmsRendererConfig.htmlComponentExternalScriptHosts`. If the site has CSP, that host must also be in `script-src`. If the host is not allowlisted, **stop** — do not invent a CDN load.
+
+Rejected: `http:`, `javascript:`, `//…`, path traversal, query/hash on same-origin paths. Disallowed URLs are not loaded (preview/dev may warn). Duplicates are dropped at render. `customJs` waits until every listed src is ready; a failed src skips inline JS.
+
+Do **not** put libraries in HTML `<script>` tags or `createElement('script')` inside `customJs`.
+
+---
+
+## Setting fields
+
+HTML/CSS/JS (long text):
+
+```
+cms_edit ["set", "@cN", "rawHtml", "--content-base64", "<b64>"]
+```
+
+`externalScripts` is an array — **not** a scalar string. Scalar `set` is rejected.
+
+```
+cms_edit ["set", "@cN", "externalScripts", "--json", "[\"/html-components/feature/lib.js\"]"]
+```
+
+On `create from-json`:
+
+```json
+{
+  "contentType": "htmlComponent",
+  "cmsLabel": "Pricing grid",
+  "fields": {
+    "rawHtml": "<div class=\"hc-root\">…</div>",
+    "customJs": "hcRoot.querySelector('.buy')",
+    "externalScripts": ["/html-components/pricing-grid/lib.js"],
+    "markdownContent": "Pricing grid"
+  }
+}
+```
+
+Use this space’s field ids from `schema htmlComponent` (`rawHtml` vs `htmlContent`). Dual-write both when the schema shows both.
+
+---
+
+## Related
+
+- `cms-edit://customer/task-create-html-component`
+- `cms-edit help create-from-json`
+- `cms-edit schema htmlComponent`

package/docs/help/fields.md

@@ -10,7 +10,7 @@ This page lists the content types managed by `cms-edit` and links to their field
 |---|---|---|
 | `page` | Web pages with a slug and content tree | `cms-edit help fields-page` |
 | `article` | Blog posts and news items | `cms-edit help fields-article` |
-| `component` | Individual content sections (hero, text block, card, etc.) | `cms-edit help fields-component` |
+| `htmlComponent` | Developer-authored HTML / CSS / JS blocks | `cms-edit help fields-html-component` |
 | `collection` | Groups of components (card grids, timelines, etc.) | `cms-edit help fields-collection` |
 | `link` | CTA button entries | Managed via `cms-edit links` |
 | `template` | Reusable page shell (header, footer slots) | Used via `templateId` in `create from-json` |
@@ -57,4 +57,5 @@ Run `cms-edit snapshot` to see current refs.
 - `cms-edit help fields-page` — page entry fields
 - `cms-edit help fields-article` — article entry fields
 - `cms-edit help fields-component` — component entry fields
+- `cms-edit help fields-html-component` — HtmlComponent (raw HTML, `externalScripts`)
 - `cms-edit help fields-collection` — collection entry fields

package/docs/help/index.md

@@ -29,6 +29,7 @@ Available topics for `cms-edit help <topic>`:
 | `fields-page` | All fields on a `page` entry |
 | `fields-article` | All fields on an `article` entry |
 | `fields-component` | All fields on a `component` entry |
+| `fields-html-component` | HtmlComponent fields including `externalScripts` |
 | `fields-collection` | All fields on a `collection` entry |
 | `fields-taxonomy` | All fields on `tagType`, `articleType`, and `tag` entries |
 | `index-sync` | Build and use the local content index (CDA sync) |

package/docs/help/lookup.md

@@ -1,6 +1,8 @@
-# Flat lookup flags (`open`, `resolve`, `nav open`)
+# Flat lookup flags (`open`, `peek`, `resolve`)
 
-cms-edit resolves entries using **explicit flags** — not positional slugs. Provide **exactly one** primary lookup flag per command. Scope flags (for example `--tag-type-name` with `--tag-name`) do not count as a second primary.
+cms-edit resolves entries using **explicit flags** — not positional slugs. Provide **exactly one** primary lookup flag per command. Scope flags (for example `--tag-type-name` with `--tag-name`, or `--nav-id` with `--nav-item-title`) do not count as a second primary.
+
+`cms-edit nav open` is separate: pass **`--nav-id` or `--nav-name`**, never `--id`. `--nav-id` alone is not a `resolve` primary.
 
 Run `cms-edit index sync` once per space (or let commands auto-sync) so catalog types resolve from the local index.
 
@@ -98,9 +100,10 @@ Navigation entries use the **`name`** field (not slug).
 | `--nav-item-id` | `navigationItem` entry ID |
 | `--nav-item-title` | `navigationItem.fields.title` |
 
-When multiple nav items share a title, add **`--nav-id`** to scope:
+When multiple nav items share a title, add **`--nav-id`** to scope `resolve` (do not use `--nav-id` alone on `resolve`):
 
 ```bash
+cms-edit nav open --nav-id <navigation-entry-id>
 cms-edit nav open --nav-name "Main header"
 cms-edit resolve --nav-item-title "Contact" --nav-id <navigation-entry-id>
 ```

package/docs/mcp/hosted-guide.md

@@ -22,7 +22,7 @@ All `save` operations create **drafts only**. A human must review and publish in
 | `cms_edit` | Run any cms-edit command via an `args` array |
 | `cms_edit_request_staged_upload` | Presigned URL for binaries. Raster/video: then `cms_edit_media` prepare. SVG/PDF/Lottie: then `asset upload --staged` |
 | `cms_edit_version` | Check the installed cms-edit version (no session required) |
-| `cms_edit_help` | Guide topics (`overview`, `workflow`, `commands`, `troubleshooting`, `hosted`) **or** playbooks (`create-from-json`, `fields-component`, …) |
+| `cms_edit_help` | Guide topics (`overview`, `workflow`, `commands`, `troubleshooting`, `hosted`) **or** playbooks (`create-from-json`, `fields-html-component`, `fields-component`, …) |
 
 ## Customer editor pack (read first)
 
@@ -88,7 +88,7 @@ Each step is a separate `cms_edit` call. Sessions persist in Redis between calls
 ["open", "--include-chrome", "--page-slug", "/pricing"]
 ```
 
-Default `open` / `peek` fetch the page or article tree and the template entry, but **not** template menu/footer/navigation. Edit nav with `nav open`. Use `--include-chrome` only when you need those trees.
+Default `open` / `peek` fetch the page or article tree and the template entry, but **not** template menu/footer/navigation. Edit nav with `["nav", "open", "--nav-id", "<id>"]` or `--nav-name` (not `--id`). Use `--include-chrome` only when you need those trees. Template `menu` is site-wide; `page.menu` overrides one page. Nested nav items are often shared — ask global vs page-specific before `set`.
 
 **Homepage (all SE Studio sites):** Contentful stores the marketing homepage slug as `index`. The live site URL is `/`. In cms-edit, `--page-slug /` and `--page-slug /index` are equivalent (both resolve to `index`). Read `cms-edit://customer/routing` for site-specific exceptions (e.g. Pedestal uses `home`).
 
@@ -311,7 +311,8 @@ OAuth is two steps: Grok obtains an MCP token, then you sign in with Contentful
 | Debug session persistence | `["diagnose"]` — reports store, userId, active session key |
 
 - **`peek` is one-shot** — prints tree and **root field values** (`rootFields` in JSON). No session is created; do not chain `read @ref` afterward.
-- **Use flat lookup flags** for `open` and `peek` — same as CLI (`--page-slug`, `--id`, etc.). See `help lookup`.
+- **`open` / `nav open` persist** the session. `preview urls /slug` follows that slug even if leftover `_mcp` is another page (JSON may include `sessionRootIgnored`).
+- **Use flat lookup flags** for `open` and `peek` — same as CLI (`--page-slug`, `--id`, etc.). See `help lookup`. `nav open` uses `--nav-id` or `--nav-name` only.
 - **`read @root`** only works after `open` (uses the active session). The hint in peek output is for terminal users who already ran `open`.
 - **Do not invent flags** — there is no `--read`, `--then`, or chained peek+read syntax. One command per `cms_edit` call.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "3.10.0",
+  "version": "3.10.2",
   "description": "CLI tool for AI agents to read and edit Contentful draft content without publish permissions",
   "repository": {
     "type": "git",

package/skills/core/SKILL.md

@@ -70,7 +70,7 @@ cms-edit open --include-chrome --page-slug /pricing
 
 `open` / `peek` fetch the page (or article) tree and the template entry, but **not** template `menu` / `footer` / navigation. Edit nav with `nav open`. Pass `--include-chrome` only when you need those trees.
 
-**Flat lookup flags:** provide **exactly one** primary flag per `open` / `resolve` / `nav open`. See `cms-edit help lookup`. Run `cms-edit index sync` so catalog types resolve from the local index.
+**Flat lookup flags:** provide **exactly one** primary flag per `open` / `peek` / `resolve`. `nav open` uses **`--nav-id` or `--nav-name` only** (not `--id`). See `cms-edit help lookup`. Run `cms-edit index sync` so catalog types resolve from the local index.
 
 ### Step 2: Read the snapshot
 
@@ -399,8 +399,9 @@ JSON output for upload (`CMS_EDIT_JSON=1`): `{ ok, id, fileName, url, mediaId?,
 ## Navigation
 
 ```bash
-# Open a navigation entry (navigation uses `name`, not slug)
+# Open a navigation entry (not --id). Navigation uses `name`, not slug.
 cms-edit nav open --nav-name "Main navigation"
+cms-edit nav open --nav-id <navigation-entry-id>
 
 # Add a new item
 cms-edit nav add --label "Pricing" --slug /pricing
@@ -409,11 +410,17 @@ cms-edit nav add --label "Docs" --href https://docs.example.com --after @c1
 # Link an existing NavigationItem (share items across navigations)
 cms-edit nav add --existing-id <navigationItem-entry-id>
 
-# Clone a navigation (duplicates all items)
+# Clone a navigation (first-level items only; nested children stay shared)
 cms-edit nav clone <source-nav-id>
 cms-edit nav clone <source-nav-id> --label "LP Nav" --slug lp-nav
 ```
 
+Template **`menu`** is site-wide. **`page.menu`** overrides one page. Header CTAs are often nested under a wrapper and **shared**. Before `set` on a nav item, ask whether the change is global or page-specific. Page-specific: new NavigationItem + cloned/new menu on `page.menu` — do not mutate the shared entry.
+
+`peek` is one-shot. `open` / `nav open` persist. `preview urls /slug` follows that slug even if session `_mcp` is another page.
+
+The items array field may be `entries`, `items`, or `navigationItems` — inspect `read @root` before `set @root … --links`.
+
 ## Create New Entries
 
 ```bash