docs(product-docs): 8.2 XSL/legacyAssembler support and migration cookbook (#4434)

[natechadwick-intsof]

Summary

Parent tracker: #2632 (grandparent #2626). Slice 5 of Phase 5 deprecation cleanup & help.

Operators now have an 8.2 XSL / legacyAssembler support statement and a short migration cookbook in product-docs:

• New page product-docs/8.2/admin/xsl-legacy-assembler.md with stable id: admin-xsl-legacy-assembler
• Existing Legacy/XSL templates keep running; new work should prefer HTML-first, Markdown, or Velocity
• No forced conversion on 8.2 upgrade; conversion is per-template and incremental
• Linked from Design templates (id:admin-design-templates), Developer Templates, Administration index, Getting Started, Upgrade Overview, Developer index, and Glossary

Ports operator facts from the engineering cookbook (docs/ai-generated/tasks/template-assembler-normalization/xsl-migration-cookbook.md) without dumping that tree.

Out of scope (intentional): XSL/legacyAssembler runtime removal, dual-run upgrade path (#4435), shim deletion (#2852), REST/WebUI/Playwright (OPEN PR #4441 hot-path files not touched).

Fixes #4434

Operator: Grok: night-issue-prs (model grok-4.6)

Test plan

1. Review the new page and id: links from Design templates / upgrade / getting-started.
2. Confirm frontmatter id: admin-xsl-legacy-assembler is unique; id: admin-design-templates unchanged.
3. Local smoke: scripts\ci-smoke-product-docs.bat (Unix: scripts/ci-smoke-product-docs.sh).

Checklist

• Product documentation — created product-docs/8.2/admin/xsl-legacy-assembler.md and linked from Design templates, admin index, getting-started, upgrade, developer index, glossary
• Unit / module tests — N/A (docs-only; no production logic)
• WebUI + Playwright — N/A (no WebUI product screen change)
• Build gates — N/A (docs-only; no Maven module sources changed)
• Cross-platform — N/A (Markdown content only; existing .bat / .sh smoke wrappers)

C3 evidence

• modules_built= (none — docs-only)
• build_evidence= scripts\ci-smoke-product-docs.bat → Built 49 page(s); ci-smoke-product-docs: OK — found tmp\product-docs-site\8.2\index.html (twice after glossary Related link)
• downstream_checked= none (C2 API shape did not apply)

C5 UI proof

N/A — no WebUI / Playwright surface.

Co-Authored by Grok Build 1.0.25 using grok-4.6 with agent night-issue-prs.

[natechadwick-intsof]

qa_deferred_quality — not assigning Human QA (@vijaya-boddipudi) for this run.

This-run PR: #4442 (parent #4434). Cycle verify: passed (docs-only; Playwright skipped_non_ui).

Not a QA candidate: product-docs only (new id:admin-xsl-legacy-assembler + id: links). No WebUI/Explorer/user-visible product flow, no installer/packaging/host-visible runtime change, and no written acceptance that requires a human UAT session after agent proof. CI product-docs-build + local scripts\ci-smoke-product-docs.bat is the automated gate; a reviewer can read the page.

Q failures (live GitHub snapshot):

• Q2 — no independent APPROVE (
  eviewDecision=REVIEW_REQUIRED; zero reviews). Self-review does not count.
• Q3 — required checks not a single green snapshot: Kilo Code Review is still IN_PROGRESS. Other checks SUCCESS/SKIPPED.

No qa task issue created. Parent #4434 left unassigned.

Co-Authored by Grok Build 1.0.25 using grok-4.6 with agent night-issue-prs-human-qa.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Overview

This is a docs-only operator increment (parent #2632, slice 5):
new product-docs/8.2/admin/xsl-legacy-assembler.md (stable id: admin-xsl-legacy-assembler) plus cross-links from Design templates,
Developer Templates, admin index, getting-started, upgrade, developer
index, and glossary.

Verification performed

• New id: admin-xsl-legacy-assembler is unique across the product-docs/
  tree (single occurrence, in the new file only).
• Every id: cross-reference resolves: admin-design-templates,
  upgrade-overview, admin-developer-templates, admin-developer-pipelines,
  developer-extensions, developer-page-packages, developer-virtual-sites,
  developer-rest, reference-glossary, admin, getting-started,
  install-overview, admin-server-ops, admin-publishing — plus all
  backward links to the new id.
• _config.yaml nav is section-level only; sub-pages discovered via
  frontmatter id/order, consistent with sibling pages. New page is
  correctly placed in the curated admin/index.md Topics list.
• $/$ rendering follows the existing convention already used in
  glossary.md / design-templates.md; static site build via
  build-cms-docs.sh.
• Diff contains only Markdown + the Erlang pre-commit artifact; no Maven,
  WebUI, REST, or Playwright surface in scope (all marked N/A, confirmed by
  diff).
• Pre-commit Erlang review artifact committed in the sanctioned location
  docs/ai-generated/code-reviews/; recommendation approve, gate pass.

Notes / minor

• Frontmatter order: 46 is shared with three pre-existing admin pages
  (developer-workflows, developer-searches, developer-roles). This is
  an established, pre-existing pattern in the tree (orders 44/45/46 are all
  shared); the new page is additionally surfaced via the curated admin
  Topics list, so sidebar ordering ambiguity is consistent with existing
  convention rather than a new defect. (Left as-is to match the tree.)

Files Reviewed (9 files)

• product-docs/8.2/admin/xsl-legacy-assembler.md (new)
• product-docs/8.2/admin/design-templates.md
• product-docs/8.2/admin/developer-templates.md
• product-docs/8.2/admin/index.md
• product-docs/8.2/developer/index.md
• product-docs/8.2/getting-started/index.md
• product-docs/8.2/getting-started/upgrade.md
• product-docs/8.2/reference/glossary.md
• docs/ai-generated/code-reviews/issue-4434-xsl-product-docs-erlang.md (artifact)

---

_{Reviewed by free · Input: 112.3K · Output: 10.9K · Cached: 301.2K}

_{Review guidance: REVIEW.md from base branch main}