natechadwick-intsof · Sep 9, 2026 · Sep 9, 2026
diff --git a/docs/ai-generated/code-reviews/issue-4433-assemblers-operator-help-erlang.md b/docs/ai-generated/code-reviews/issue-4433-assemblers-operator-help-erlang.md
@@ -0,0 +1,45 @@
+# Erlang review — #4433 product-docs assemblers operator help
+
+| Field | Value |
+|-------|--------|
+| **Date** | 2026-09-09 |
+| **Branch** | `feat/issue-4433-assemblers-operator-help` |
+| **Base** | `origin/main` |
+| **Reviewer** | Erlang (independent of implementer) |
+| **Recommendation** | **approve** |
+| **May commit/push** | **yes** |
+| **Gate** | pass |
+
+## Summary
+
+Docs-only operator help for Design / Developer Templates assembler choice
+(HTML-first default, Markdown, Velocity; Legacy/XSL compatibility only). Stable
+frontmatter `id: admin-design-templates` is unchanged. No pipeline hot-path
+files. `scripts/ci-smoke-product-docs.sh` built 48 pages and emitted
+`tmp/product-docs-site/8.2/index.html`. Dollar-brace examples use HTML entities
+so Virtual Site HTML-first layout does not eat them.
+
+## Scope
+
+- `product-docs/8.2/admin/design-templates.md`
+- `product-docs/8.2/admin/developer-templates.md`
+- `product-docs/8.2/getting-started/index.md`
+- `product-docs/8.2/reference/glossary.md`
+- Uncommitted vs HEAD; no Maven / WebUI / REST / Playwright in this slice
+- Memory patterns: product-docs companion; no file I/O in product code
+- Cross-platform path review: **N/A** (Markdown content only; smoke uses existing `scripts/ci-smoke-product-docs.sh` + `.bat`)
+
+## Issues
+
+None (bug / missing tests / non-portable I/O).
+
+### nit
+
+- Markdown pipe tables remain as CommonMark source in assembled HTML (pre-existing
+  Virtual Site Markdown table rendering). Not introduced uniquely by this slice.
+
+## Product-docs / tests / C5
+
+- Product documentation **is** the change.
+- Unit tests N/A (no production logic).
+- Playwright / C5 N/A (no WebUI).
diff --git a/product-docs/8.2/admin/design-templates.md b/product-docs/8.2/admin/design-templates.md
@@ -1,10 +1,10 @@
 ---
 id: admin-design-templates
 title: Design templates
-description: Create, edit, and delete modern assembly templates in the Design SPA; classic list bookmarks redirect here
+description: Create, edit, and delete modern assembly templates; choose HTML-first, Markdown, or Velocity assemblers (prefer over Legacy/XSL)
 version: "8.2"
 order: 44
-tags: [admin, design, templates, ui]
+tags: [admin, design, templates, ui, assembler]
 ---
 
 # Design templates
@@ -79,12 +79,15 @@ is `0-4-602`.
    Names cannot contain spaces and must be unique.
 3. Optionally enter a **Label** and **Description**. If you leave the label empty, the
    server uses the name.
-4. Choose an **Assembler**. New templates default to **HTML-first** (recommended). Markdown
-   and Velocity are also supported modern assemblers. Prefer those over Legacy / XSL.
+4. Choose an **Assembler**. New templates default to **HTML-first** (recommended, ★).
+   Markdown and Velocity are also recommended modern assemblers. Prefer those over
+   **Legacy / XSL**. See [Choose an assembler](#choose-an-assembler-html-first-markdown-velocity).
 5. Choose **Create**.
 
 The catalog list refreshes and shows the new row. Open the row to edit assembler, slots,
-source, and JEXL bindings.
+source, and JEXL bindings. If you omit **Assembler** on REST create
+(`POST /services/templates`), the server also defaults to HTML-first
+(`Java/global/percussion/assembly/htmlAssembler`).
 
 Create persists through `POST /services/templates` with a `TemplateDetail` body. The server
 stores a shared assembly template (package/manifest model). **No Widget Builder XML file is
@@ -93,6 +96,116 @@ written.**
 If create fails (duplicate name, invalid name, or server error), the dialog stays open and
 shows an operator-facing message. Correct the fields and try again.
 
+## Choose an assembler (HTML-first, Markdown, Velocity)
+
+Each assembly template stores an **assembler** (a render plugin). Percussion CMS 8.2
+evaluates the template’s **JEXL bindings** in order, then the assembler turns the
+template **source** into output (usually HTML).
+
+On **Design**, the **Assembler** list on **Create template** and on the template
+editor shows the catalog below. Recommended modern choices are marked with a star
+(★). The editor option text also includes the short extension name
+(`htmlAssembler`, `markdownAssembler`, `velocityAssembler`, …).
+
+**Prefer HTML-first, Markdown, or Velocity for new templates.** Use **Legacy / XSL**
+only when an existing stylesheet-based template still needs that path. Do not start
+new Design work on Legacy / XSL.
+
+### Recommended modern assemblers
+
+| Assembler (picker) | Extension stored on the template | Use when | Source language |
+|--------------------|----------------------------------|----------|-----------------|
+| **HTML-first** ★ (default) | `Java/global/percussion/assembly/htmlAssembler` | Mostly static HTML with a few bound values; no Velocity macros | HTML plus <code>&#36;{dotted.path}</code> placeholders |
+| **Markdown** ★ | `Java/global/percussion/assembly/markdownAssembler` | Prose or structured text that should become HTML | CommonMark Markdown; placeholders first, then Markdown → HTML |
+| **Velocity** ★ | `Java/global/percussion/assembly/velocityAssembler` | Macros, loops, `#parse`, Active Assembly slot macros, existing Velocity snippets | Velocity 2.x plus JEXL-bound `$` variables |
+
+HTML-first is the **create default** on Design and on `POST /services/templates` when
+the body omits `assembler`.
+
+### How to choose
+
+1. You need macros, loops, `#parse`, or Active Assembly Velocity macros → **Velocity**.
+2. The body is mostly fixed HTML with a handful of field or system values → **HTML-first**.
+3. The body is long-form content (headings, lists, links) that should render as HTML → **Markdown**.
+4. The template is an existing XSL / XML-application variant that still works → leave **Legacy / XSL**.
+   Do not convert it on this page; XSL migration is a separate operator topic.
+
+You can change the assembler later on the Design editor. Changing assembler does **not**
+rewrite source automatically — update **Template source** so it matches the new language
+(HTML placeholders, Markdown, or Velocity), then **Save**.
+
+### HTML-first and Markdown placeholders
+
+HTML-first and Markdown fill **only** dollar-brace dotted paths from JEXL binding
+results (missing keys become empty).
+
+| Rule | Detail |
+|------|--------|
+| Form | <code>&#36;{title}</code>, <code>&#36;{sys.mimetype}</code> |
+| Not supported | Bare `$title` (too easy to confuse with HTML or scripts), Mustache `{{ }}`, Velocity directives (`#if`, `#foreach`, `#parse`) |
+| Lookup | Binding variable `title` or `$title`; nested maps via `sys` / `$sys` then child keys |
+| Missing | Empty string (the token does not stay in the output) |
+
+Do **not** paste Velocity macros into an HTML-first or Markdown template. If you need
+`#parse` or slot macros, switch the assembler to **Velocity** and author Velocity source.
+
+Markdown runs **placeholders first**, then CommonMark → HTML. Write Markdown in the
+source editor (headings, lists, links). HTML-first leaves the source as HTML after
+placeholder substitution (no Markdown pass).
+
+### JEXL bindings
+
+Bindings stay **JEXL** for HTML-first, Markdown, and Velocity. On the Design editor,
+add, edit, or remove rows (variable + expression), then **Save** (full replace).
+Bindings run **before** the assembler renders source.
+
+Typical modules you will see in expressions:
+
+| Module | Role |
+|--------|------|
+| `$sys` | Assembly context (`template`, `mimetype`, `charset`, `site`, slot helpers, …) |
+| `$rx` | JEXL tools (`asmhelper`, `codec`, `link`, `location`, `nav`, `string`, …) |
+| `$perc` | CM1 page context (regions / widgets / theme helpers) — mainly with **Page (CM1)** |
+
+### Change the assembler on an existing template
+
+1. Open **Developer → Design** (template library) and open the template row.
+2. Under **Assembler**, choose **HTML-first**, **Markdown**, or **Velocity** (★).
+3. Adjust **Template source** for that language. For Velocity, you can insert built-in
+   macros from **Developer → Templates** (**Insert snippet**). See
+   [Developer Templates](id:admin-developer-templates).
+4. Confirm **JEXL bindings** still match the names you reference in source.
+5. Choose **Save**. Success and validation stay on the editor.
+
+**Developer → Templates** shows the stored assembler extension name as read-only
+metadata. Change the assembler on **Design**, then reopen Developer Templates if you
+need export XML or snippet insert.
+
+### Other entries in the Assembler list
+
+These remain in the picker for existing templates and specialized output. They are
+**not** the default for new snippet-style design.
+
+| Assembler (picker) | Extension | Operator note |
+|--------------------|-----------|----------------|
+| **Page (CM1)** | `Java/global/percussion/assembly/pageAssembler` | CM1 page context and `$perc` (page/region composition). Keep on shipped page templates such as `perc.page`. It is page context plus a text render path — not a fourth authoring language. |
+| **Legacy / XSL** | `Java/global/percussion/assembly/legacyAssembler` | Compatibility only. Existing XML applications and stylesheets continue to run. Do not choose this for new templates. |
+| **Binary** | `Java/global/percussion/assembly/binaryAssembler` | Binary / resource output. |
+| **Dispatch** | `Java/global/percussion/assembly/dispatchAssembler` | Dispatch to another template. |
+| **Database** | `Java/global/percussion/assembly/databaseAssembler` | Database result-set output. |
+
+If a template already uses a custom extension that is not in this list, Design keeps
+that value as **Current (custom)** so you can save without forcing a catalog assembler.
+
+### What not to do
+
+- Do not delete or disable **Legacy / XSL** on the server to “clean up” — existing
+  sites may still assemble through it.
+- Do not treat definition-XML shims or Workbench XML export as the way to pick a
+  modern assembler. Create and edit assemblers on Design (or REST `assembler` on
+  `POST` / `PUT /services/templates`).
+- Do not mix Velocity directives into HTML-first or Markdown source.
+
 ## Delete a template
 
 1. On the Templates library, choose **Delete** on the row you want to remove. You can
@@ -144,9 +257,10 @@ There is no Design SPA import wizard. See
 
 Open a template row from the library. The editor (same Design tab) lets you:
 
-- Change the **assembler**
+- Change the **assembler** (prefer HTML-first, Markdown, or Velocity — see
+  [Choose an assembler](#choose-an-assembler-html-first-markdown-velocity))
 - Edit **slot** layout and styles (orientation, columns, classes)
-- Edit Velocity / HTML / Markdown **source**
+- Edit Velocity / HTML / Markdown **source** to match the assembler
 - Add, edit, or remove **JEXL bindings** (saved as a full replace)
 
 Choose **Save**. Success and validation errors stay on the editor. Use **Templates** to
@@ -162,10 +276,11 @@ related upgrade-only JSPs) until those flows are signed off on the SPA. Bookmark
 
 ## Related
 
-- [Developer Templates](id:admin-developer-templates) — catalog export/import XML
+- [Developer Templates](id:admin-developer-templates) — catalog export/import XML and Velocity snippet insert
 - [REST API](id:developer-rest) — `GET`/`POST`/`PUT`/`DELETE /services/templates`, Admin `GET .../export`, and `POST /services/templates/import`
 - [Extensions & packages](id:developer-extensions)
 - [Developer Extensions](id:admin-developer-extensions)
 - [Product page packages](id:developer-page-packages)
+- [Glossary](id:reference-glossary)
 - [Navigation & site structure](id:admin-architecture-navigation)
 - [Administration](id:admin)
diff --git a/product-docs/8.2/admin/developer-templates.md b/product-docs/8.2/admin/developer-templates.md
@@ -1,7 +1,7 @@
 ---
 id: admin-developer-templates
 title: Developer Templates
-description: Export and import assembly-template design XML from Developer Templates, edit source with Velocity snippet insert, bindings, and slots
+description: Export and import assembly-template design XML from Developer Templates, edit source with Velocity snippet insert, bindings, and slots; assembler choice lives on Design
 version: "8.2"
 order: 45
 tags: [admin, developer, templates]
@@ -62,10 +62,16 @@ Integrators can also call `POST /services/templates/import` with
 
 ## Edit from detail
 
-Open a template row to change label, description, assembler source, JEXL
+Open a template row to change label, description, template source, JEXL
 bindings, and contained slots, then **Save**. **Export XML** is available on the
 same toolbar. Object ACL for the template is on the detail panel.
 
+The **assembler** extension name (for example
+`Java/global/percussion/assembly/htmlAssembler`) is **read-only** on this
+catalog. To create a template or to switch **HTML-first**, **Markdown**, or
+**Velocity** (and to avoid **Legacy / XSL** for new work), use
+[Design templates](id:admin-design-templates).
+
 Create and delete of modern assembly templates remain on
 [Design templates](id:admin-design-templates) — this Developer catalog does not
 add those actions.
@@ -86,7 +92,12 @@ shipped assembly macros).
    double-click the row).
 
 The selected macro text is inserted at the caret (or replaces the selection).
-Save the template when you are ready. The snippet library does **not** edit
+Save the template when you are ready. Snippets are **Velocity** macros — they
+belong on templates whose assembler is **Velocity**. Do not insert them into
+HTML-first or Markdown source; change the assembler on
+[Design templates](id:admin-design-templates) first if you need macros.
+
+The snippet library does **not** edit
 System/User Velocity configuration files (SY-02); it only inserts catalog text
 into the template body. Integrators can call the same REST catalog directly —
 see [REST API](id:developer-rest) (Velocity snippets).
@@ -97,7 +108,7 @@ Automated H2 surface coverage lives in
 
 ## Related
 
-- [Design templates](id:admin-design-templates)
+- [Design templates](id:admin-design-templates) — create/delete and HTML-first / Markdown / Velocity assembler picker
 - [REST API](id:developer-rest)
 - [Object ACL & default template](id:admin-object-acl)
 - [Administration](id:admin)
diff --git a/product-docs/8.2/getting-started/index.md b/product-docs/8.2/getting-started/index.md
@@ -37,7 +37,8 @@ This section covers how to obtain, install, upgrade, and take first steps with P
    [Design templates](id:admin-design-templates).
 4. Create or open a **Site**, confirm Explorer navigation, and open the React Content Editor from Explorer **Edit** or **Home → Create** (page, blog, or asset). Those surfaces do not open leftover `?view=editor` or `editAsset.jsp` — those bookmarks redirect to `spa.jsp?entry=editor`. A published-page `perc_linkback_id` that no longer exists still opens that editor host with a missing-item message (not leftover Content Editor HTML).
 5. Open **Developer → Design** to list assembly templates and edit source, JEXL bindings, assembler,
-   and slots. See [Design templates](id:admin-design-templates).
+   and slots. New templates default to **HTML-first**; prefer HTML-first, Markdown, or Velocity
+   over Legacy / XSL. See [Design templates](id:admin-design-templates).
 6. Review [Server operations](id:admin-server-ops) for ports, service control, and logs.
 
 ## Related

diff --git a/product-docs/8.2/reference/glossary.md b/product-docs/8.2/reference/glossary.md
@@ -11,7 +11,10 @@ tags: [reference]
 
 | Term | Definition |
 |------|------------|
+| **Assembler** | Render plugin on an assembly template. 8.2 recommended choices are **HTML-first**, **Markdown**, and **Velocity**. **Legacy / XSL** is compatibility only. See [Design templates](id:admin-design-templates). |
 | **Assembly** | Process of merging content with templates/variants to produce deliverable output |
+| **HTML-first assembler** | Default modern assembler (`htmlAssembler`): HTML source with <code>&#36;{dotted.path}</code> placeholders from JEXL bindings; no Velocity directives |
+| **Markdown assembler** | Modern assembler (`markdownAssembler`): placeholders, then CommonMark → HTML |
 | **Asset** | Shared content fragment referenced by pages |
 | **CM1** | Marketing name historically used for the modern Percussion CMS product line |
 | **CMS** | Content Management System — this product |
@@ -29,12 +32,14 @@ tags: [reference]
 | **REST adaptor** | Interface in `rest` implemented by sitemanage apibridge |
 | **Site** | Organizational and publishing unit (traditional or Virtual) |
 | **Template / variant** | Presentation definition used during assembly |
+| **Velocity assembler** | Modern power assembler (`velocityAssembler`): macros, loops, `#parse`, Active Assembly macros |
 | **Virtual Site** | Site whose content comes from an external source (e.g. Git filesystem) |
 | **Workflow** | State machine governing edit/approve/publish rights |
 | **WebUI** | Primary browser UI for editors and admins |
 
 ## Related
 
+- [Design templates](id:admin-design-templates)
 - [Sites & content structure](id:admin-sites)
 - [Product page packages](id:developer-page-packages)
 - [Virtual Sites](id:developer-virtual-sites)