docs(#2833): Assemblers and Templates implementer guide

[natechadwick-intsof]

Summary

Phase 5 slice 1 of #2632 (epic #2626): ship a single Assemblers and Templates implementer guide consolidating Phase 0–4 ADRs and dual-run notes.

• New: docs/ai-generated/tasks/template-assembler-normalization/implementer-guide.md
• Covers: one Template model, JEXL bindings (ADR-001), assembler set + ${path} (ADR-002), slots layout/styles (ADR-003), modern component-package.json (ADR-004), dual-run shim status, dual-ship vs native page install
• Links ADRs 001–004, dual-run/dual-ship docs, inventories, binding modules, parity notes
• Linked from task README.md and adr/README.md
• Docs-only; no product behavior change
• Does not include XSL cookbook (issue 2632 slice 2: XSL migration cookbook + Rhino note #2834) or Design SPA help (issue 2632 slice 3: definition-XML shim removal criteria + residual #2835)

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

Parent tracker: #2632 · Grandparent: #2626 · Related packaging: #2630

Test plan

• Relative links from implementer guide resolve within the task folder (ADRs, dual-run, dual-ship, manifest, inventories)
• Task README lists implementer guide as the single entry point
• No Maven modules changed (docs-only)
• Human skim of implementer guide for accuracy vs ADRs (optional)

Build evidence (C3)

Field	Value
modules_built	none (docs-only under docs/ai-generated/)
build_evidence	N/A — no pom.xml / sources / tests changed; Pre-PR Maven clean install not required for docs-only
downstream_checked	none (C2 N/A — no API/type shape changes)

Product documentation

• N/A — engineering implementer guide under docs/ai-generated/; not a customer/operator product-docs surface. Product help rewrite remains a later Phase 5 item.

Fixes

Fixes #2833
Refs #2632 #2626 #2630

Co-Authored by Grok Build using grok-4.5 with agent main.

[kilo-code-bot]

Code Review Summary

Status: 3 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
WARNING	1
SUGGESTION	2

Issue Details (click to expand)

WARNING

File	Line	Issue
projects/sitemanage/src/main/java/com/percussion/sitemanage/importer/data/PSImportLogEntry.java	36	Adding serialVersionUID = 1L to a previously-unUIDed Serializable Hibernate @Cache entity changes the deserialization contract — cached instances from a prior runtime may fail with InvalidClassException

SUGGESTION

File	Line	Issue
product-docs/8.2/admin/content-explorer.md	6	Duplicate order: 42 with product-docs/8.2/admin/users-roles.md — duplicate sort keys may produce non-deterministic nav ordering
docs/ai-generated/tasks/template-assembler-normalization/definition-xml-shim-removal-criteria.md	41	PowerShell-only Get-ChildItem -Recurse without noting it requires PowerShell or providing a Unix equivalent

Files Reviewed (210 files)

• WebUI/src/main/ts/contentExplorer/ContentExplorerShell.tsx - action enablement filtering
• WebUI/src/main/ts/contentExplorer/actionEnablement.ts - new action enablement helpers
• WebUI/src/test/ts/contentExplorer/ContentExplorerShell.test.tsx - toolbar/context menu filtering test
• WebUI/src/test/ts/contentExplorer/actionEnablement.test.ts - new unit tests for enablement helpers
• deployer/src/main/java/com/percussion/deployer/objectstore/*.java - generics/final xlint cleanup
• deployer/src/test/java/... - new typed tests + xlint tests
• modules/perc-packages/src/main/java/.../PSWidgetXmlDualShip.java - new dual-ship bridge (489 lines)
• modules/perc-packages/src/main/java/.../PSLegacyDefinitionXmlShim.java - modern widget manifest selection
• modules/perc-packages/src/main/resources/Packages/ - ~50 new component-package.json + template dual-ship artifacts
• modules/perc-auditlog/src/main/java/.../codes/*.java - new error code enums (Server, Http, Assembly, etc.)
• modules/perc-auditlog/src/test/java/... - new error code tests
• projects/sitemanage/src/main/java/... - data-layer typed/cleanup changes
• system/src/main/java/com/percussion/data/* - xlint batch 5 generics/final
• docs/ai-generated/tasks/template-assembler-normalization/ - implementer guide + ADRs
• specs/2400-dce-explorer-parity/ - DCE explorer parity specs
• product-docs/8.2/admin/content-explorer.md - new product doc

Fix these issues in Kilo Cloud

Previous Review Summaries (2 snapshots, latest commit efbce11)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit efbce11)

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
SUGGESTION	1
WARNING	1

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
docs/ai-generated/tasks/template-assembler-normalization/README.md	55	Duplicate implementer-guide.md table entry — line 53 already lists it as the single entry point

WARNING

File	Line	Issue
modules/perc-packages/src/main/java/com/percussion/packages/pagexml/PSPageXmlNativeInstall.java	181	Error message uses original-case stem for the expected mapping key, but the lookup now normalizes to lower-case (stemKey). A mixed-case manifest stem like perc.base.Box will see "Expected key 'perc.base.Box.templateDef'" while the actual key it must write is perc.base.box.templateDef — misleading during debug.

Files Reviewed (40 files)

• deployer/src/main/java/com/percussion/deployer/objectstore/PSDeployComponentUtils.java - generics cleanup
• deployer/src/main/java/com/percussion/deployer/server/PSAppTransformer.java - xlint batch 5 generics/final
• deployer/src/main/java/com/percussion/deployer/objectstore/idtypes/*.java - 15 classes marked final
• deployer/src/test/java/... - 2 new test classes
• modules/perc-packages/src/main/java/.../PSPageXmlNativeInstall.java - case-insensitive stem lookup
• modules/perc-packages/src/main/java/.../PSWidgetXmlPackageCompiler.java - perc.Test residual
• modules/perc-packages/src/test/java/... - 2 updated + new test resources
• docs/ai-generated/... - 8 docs updated/created
• AGENTS.md - Product documentation HARD GATE added
• .github/pull_request_template.md - new PR template
• product-docs/README.md - agent gate note
• specs/2400-dce-explorer-parity/contracts/gap-matrix.md - Object ACL cross-epic disposition

Fix these issues in Kilo Cloud

Previous review (commit da7acd9)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (3 files)

• docs/ai-generated/tasks/template-assembler-normalization/README.md
• docs/ai-generated/tasks/template-assembler-normalization/adr/README.md
• docs/ai-generated/tasks/template-assembler-normalization/implementer-guide.md

---

_{Reviewed by step-3.7-flash · Input: 169.4K · Output: 29.2K · Cached: 2.3M}

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

[natechadwick-intsof]

Sibling Phase 5 docs landed in PR #2851 (#2834):

• xsl-migration-cookbook.md
• rhino-js-extension-note.md

When convenient, please add reciprocal links from implementer-guide.md (Related / Phase 5 section) to those paths. The cookbook already links to implementer-guide.md.

Co-Authored by Grok Build using grok-4.5 with agent main.

[natechadwick-intsof]

Rebase onto main (conflict resolution): Rebased docs/issue-2833-assemblers-templates-implementer-guide onto current origin/main (bade47fcef).

Conflict: docs/ai-generated/tasks/template-assembler-normalization/README.md — kept both sides' document table rows:

• main: definition-xml-shim-removal-criteria.md (issue 2632 slice 3: definition-XML shim removal criteria + residual #2835)
• PR: single-entry-point implementer-guide.md + dual-ship-page-template-retirement.md
• Dropped redundant shorter implementer-guide row (same intent as prior review mitigation)

Force-with-lease push: tip 0e49b5ef95. Docs-only; no Maven.

Co-Authored by Grok Code using grok with agent night-issue-prs-followup.