Rewrite the README and context guide, incorporating #114 and current 1.5 contracts

[jmanico]

Reviewed 2026-09-25 (America/Los_Angeles) against main at bd249f5. Execution order and cross-issue ownership: #169. Batch 05.

This scope replaces the dated implementation prescriptions in the original report and earlier comments; linked historical evidence remains useful but must be rechecked before implementation.

Canonical README work item

Absorbs #114's remaining work. #162 already supplied runtime compatibility documentation; #151 added JSON and #155 added ordinary untagged-template support. The new guide must describe those contracts, not historical statements that JSON/templates are categorically unsupported. #112 owns urgent ESAPI dependency/release wording first.

• Provide a current context-selection table and anti-pattern guidance, including String/Writer variants, JSON string-content versus full serialization, ordinary versus tagged templates, URL validation/component encoding and surrounding HTML contexts. Keep package Javadocs consistent with Align ESAPI URL-component semantics and define safe adapter context contracts #100/Complete forUri deprecation across registry and tag APIs without removing 1.x support #130 and the tested API.
• Consolidate build instructions around normal verify and the adopted wrapper (Pin Maven bootstrap and toolchain policy; evaluate verified dependency trust separately #122), explaining optional Docker tests and linking compatibility diagnostics. Do not reintroduce the removed benchmark profile.
• Document all four coordinates using a verified released version; distinguish GitHub signed artifacts, Central availability and snapshots. Preserve the 1.4.1 security/pending notices until Complete release readiness: Central 1.4.1 publication and independent maintainer recovery #111 verifies publication. Link SECURITY.md, KEYS, release verification and OWASP guidance; a Central badge is optional and must not imply the latest fixed release is already available there.
• Explain basic/advanced taglib identifiers, supported bindings and XML 1.1 restrictions; identifiers need not resolve as web URLs. Include version-sensitive EL evaluation guidance and state that javax/Jakarta adapter JARs must not coexist on one classpath/module path.
• Reuse Add isolated packaged-consumer compatibility CI across Java 8–25 #162's per-artifact runtime matrix and Constrain OSGi imports to actual adapter API requirements and freeze bundle identities #137's BSN/import-range decisions; preserve existing JPMS/automatic names and add a usable module example.
• Document zero-dependency core versus adapter graphs and non-goals. Any ecosystem comparison must be accurate and sourced; avoid unverified performance/security superiority claims. Inventory dependency licenses with provenance without offering unsupported legal conclusions.
• Set a compatibility/versioning policy based on observable contract changes: more escaping can also break exact-output consumers, so never declare every such change automatically patch-safe. Preserve Java 8/API/module identity promises for 1.x; discuss major decisions in Decide future-major compatibility policy without committing 1.x to breaking changes #142.
• Align release history with Create a verified changelog and reuse the existing security release-notes structure #115, contributor details with Add accurate contributor guidance and validated community/review metadata #127 and site essentials only if retained under Retire unused site tooling while preserving documentation and useful reports #96. Changes to the separate OWASP website are tracked/coordinated separately.

Batch 01 migration input

#100 and #130 are complete through #170 and #172. Reuse the shared forUri migration section and release-specific ESAPI URL/context guidance in the future README consolidation. Preserve the distinction between legacy retained forUri behavior, the adapter's unreleased 1.5 component-encoding change, ESAPI form encoding, application URL validation, and quoted HTML/CSS/JavaScript contexts. Adapter null/Unicode behavior and upstream security support remain explicitly documented. This input does not complete the broader #128 scope.