Rewrite the security, listing-path and CHANGELOG documentation

[field123]

Parent

#553 — Spec: one session for Elastic Path identity

What to build

A storefront developer reading the documentation finds the design the package actually has, not
the one it reversed — and finds one place, not three contradicting ones, telling them which
listing component to use.

Ships with the breaking release.

Spec stories 36, 37.

Acceptance criteria

• The security documentation describes the shipped design: one encrypted session cookie, no Elastic Path credential in the browser, browser-originated calls carrying identity through the storefront's own origin.
• The changelog states plainly that a documented earlier decision was reversed, and explicitly retires the earlier claim — so two entries cannot assert opposite designs with nothing connecting them.
• Guidance on choosing a listing path exists in exactly one place, and splits on store capability rather than page type.
• That guidance states the server-rendering limitation and the design-time limitation plainly, rather than leaving a developer to discover either.
• The changelog records changed defaults and removed capabilities, not only deleted configuration — including the cart default and the design-time preview override.
• The development-server warning survives and is strengthened, since the envelope now carries the account credential.
• No documented field, route or property remains that the code does not have.

Blocked by

• Delete the browser token surface and mark the unremovable registrations inert #544 — Delete the browser token surface and mark the unremovable registrations inert

The tracker's dependency graph on this issue is authoritative; this list mirrors it.

---

Below is the original ticket, kept intact — it carries the research and decisions from #486, #495, #523 and #524.

In brief

The documentation changes that ship with the breaking release.

Three things need writing. The security section currently describes the browser-held credential as a deliberate safety property; it is not one, and the reasoning has to be replaced rather than edited. Guidance on which product-listing component to use is currently stated three times in two files, all three splitting on the wrong criterion. And the changelog needs to say plainly that the project reversed a documented earlier decision, or two changelog entries will assert opposite designs with nothing connecting them.

An interim version of the security section already shipped with ADR-0003, stating what is true today and pointing at the decision. This replaces it with the finished state.

Part of the ADR-0003 token architecture. Ships with the breaking release. Scope from #490, #494, #495, #517, #518 and #524.

README

• Rewrite the security section to the destination state: one encrypted session cookie, no Elastic Path credential in the browser, every browser-originated call carrying identity through the storefront's own origin. The interim text committed with ADR-0003 states today's two-token reality and points at the ADR; this replaces it.
• The next dev caveat stays and matters more, since the envelope now carries the account token.
• README.md:412 — session.user?.accountId is a field nothing writes.
• README.md:471 cuts down to a link to the COMPONENTS.md section below. Restating the listing-path guidance in both files is how the current drift happened.
• README.md:33 — the cartMergeStrategy: "replace" line goes with the enum.
• API route tables updated.

COMPONENTS.md

One canonical "Choosing a listing path" section carrying:

• The rule: catalog search for everything, SSR and SEO-critical pages included; EPProductListProvider is the supported on-ramp for stores without a search index. The discriminator is store capability, not page type — which retires the framing of all three existing passages (README.md:471, COMPONENTS.md:795, COMPONENTS.md:844), each of which splits the paths on sort and none of which mentions the search index.
• The switch recipe: three components swap (provider, repeater, pagination), plus re-pointing the SSR seed. Card layouts survive — both repeaters DataProvide the same currentProduct.
• No deprecation signal on either path. Neither can be removed regardless.
• The SSR caveat: server-rendered catalog search is the unrefined default first page. Category pages scoped by baseFilter render correctly; deep-linked search and refinement URLs render unrefined and self-correct after hydration.
• The design-time limitation: a designer on a catalog-search PLP sees "Sample" fixtures permanently, because the canvas never mounts the provider's inner component. A designer on a list-provider PLP sees the store's real products and extension slugs.
• COMPONENTS.md:118 — accountId is described as "EP account token for account-member carts", wrong on both counts.

Two corrections to carry: the example app's export const revalidate = 60 is inert, because cookies() already forces every EP page dynamic; and there is no useNextHeaders symbol in src/ (an experiment artefact in an earlier note).

CHANGELOG

Lead architectural, then the lists. README.md and the 0.3.0 entry currently document the browser anonymous token as a deliberate property; an entry that only lists removals leaves two changelog entries asserting opposite designs with nothing saying the second supersedes the first.

• Direction change first, with an explicit line retiring the 0.3.0 claim.
• Then ### Removed, ### Deprecated, ### Changed.
• ### Changed must record the changed cart default — the package shipped a documented "merge" default and the new default does not merge.
• Record the removed design-time capability (the cart-id preview override), not only deleted config.
• Record the canvas change as a line, not a heading, with its remedy: a hostless canvas artboard's catalog read becomes relative, so it resolves against whatever document serves the artboard. With an app host configured the designer gets better data than today; with no app host it resolves at the renderer, 404s, and drops to the labelled "Sample" mock floor. No removal in the lists implies it, so it must be named.

Blocked by: the deletion issue.

---

ADR-0003: plasmicpkgs/commerce-providers/elastic-path/docs/adr/0003-one-session-for-elastic-path-identity.md. Map: #486. Issue set: #496.