docs: document Sidekick Experimentation panel setup for v2

[keepthebyte]

Summary

v2 moved the experiment/audience/campaign simulation UI out of the plugin's own injected overlay and into a hosted MFE panel loaded by the AEM Sidekick browser extension, but I couldn't find any documentation describing how to actually wire that up in a project. setupCommunicationLayer in src/index.js implements the postMessage handshake side of it, but a consuming project still needs to register a Sidekick plugin and load a page-side listener script for the toolbar button to do anything.

I worked this out first-hand while instrumenting a real (non-Xwalk) project against v2, including two non-obvious gotchas that cost real debugging time:

• For a project already migrated to AEM's unified ("helix5") config format (e.g. via Experience Workspace), Sidekick reads its plugin list from the persisted admin config, not a live read of tools/sidekick/config.json off the code bus — so just committing that file isn't enough.
• That same admin config API has its PUT/POST verbs inverted from typical REST conventions: PUT only creates a config and fails with config already exists if one is already there; POST is what updates it.
• If the page-side listener script is never loaded (nothing wires it up automatically — it's a classic, non-module script), clicking the Sidekick button silently does nothing: the button correctly dispatches its custom event, there's just nobody listening, so there's no console error either.

Changes

• New "Enabling the Sidekick Experimentation panel" section in README.md covering all three setup steps, plus the config-propagation and PUT/POST gotchas above.
• documentation/sidekick/config.json and documentation/sidekick/aem-experimentation.js as copy-pasteable reference files matching what's inlined in the README.
• A correction to documentation/experiments.md's "Simulation" section, which still described the v1 in-page overlay as automatic, and referenced the wrong query parameter name (audience instead of experiment) for forcing a variant.

Test plan

• Verified documentation/sidekick/config.json is valid JSON and documentation/sidekick/aem-experimentation.js has valid JS syntax.
• All of this was validated against a live project: registered the plugin, hit the exact config already exists / PUT-vs-POST issue and confirmed the POST workaround, and confirmed the Sidekick button was a silent no-op until the listener script was actually loaded from head.html.
• Would appreciate a maintainer sanity-check on whether the MFE URL / panel behavior described matches current internal expectations, since I only have external visibility into the hosted panel itself.

Opening as a draft since I'm an external contributor working from a downstream project, not an AEM Engineering team member — happy to adjust scope, tone, or wording to match your preferred docs style.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ramboz]

Thanks for this @keepthebyte — the reference implementation and the write-up of the helix5 / PUT-vs-POST gotchas were exactly what was needed to pin down the problem.

We opted to fix this in the plugin itself rather than as project-side docs: #62 moves the listener/MFE-loading logic into the plugin's loadLazy(), so consuming projects no longer copy aem-experimentation.js into tools/sidekick/ or add a <script> to head.html (which also removes the CSP-nonce and silent-no-op traps you documented). It keeps the genuinely project-side parts of your PR — the Sidekick config.json registration and the helix5 admin-config note — in the README, and adds a simulationUI option to distinguish the EDS + Sidekick surface from the Universal Editor.

Given that, I'd suggest we close this one in favor of #62 once it lands, but I've kept your documentation/experiments.md fixes and config reference there so nothing is lost. Credited you in the PR description. 🙏