docs(experiments): spec for swapping the list to the server-side contract (#37007)

[oidacra]

Spec-first PR for #37007, using the single-PR flow: the specification lands as the initial commit and the implementation will land in this same PR once its entry condition is met.

Closes #37007. Visual review page (summarizes; the spec decides): https://claude.ai/code/artifact/908c4144-2b25-40f9-a2d4-abdc18b1000b

What the spec defines

Swap the Experiments portlet list from the #36989 client-side interim (download every experiment plus a bulk page lookup, then fake paging, sorting, filtering, counts and site scoping in the browser) to the server-side contract on GET /api/v1/experiments. Pure consumer swap: no new endpoint; every new query parameter is additive and optional, so existing callers are untouched.

• One request per view change carrying page, per_page, orderby, direction, filter, status, goal, created_by, running_from, running_to, siteId; the pager total comes from pagination.totalEntries; the interim client-side utilities are deleted.
• The URL contract stays byte-identical for every pre-existing parameter — the Experiments Portlet — E2E test suite (incl. flag-off regression of the old flow) #37006 deep-link E2E suite must pass unchanged. The three new parameters appear only when their filter is active.
• Two stakeholder-requested filters (added 2026-08-27): by creator (created_by) and by running date range (running_from/running_to, inclusive overlap semantics, orthogonal to the status filter). Their two toolbar controls are the only permitted exception to the "no component changes" boundary.
• Accepted behavior changes, owned by Add pagination, sorting, filtering and permission checks to the Experiments list endpoint #36823: permission narrowing (users see only experiments on pages they can edit) and free-text search no longer matching descriptions.

Entry condition: implementation blocked

#36823 (the backend contract, expanded scope) is open with no implementation PR, and none of the contract is on main yet. Implementation in this PR starts only after the expanded #36823 lands and the dependency state is re-verified. Details in the spec's Scope Note and Dependencies sections.

[claude]

Claude finished @oidacra's task in 1m 13s —— View job

---

SDK Compatibility Analysis

• Read SDK breaking-change categories reference
• Get full PR diff
• Analyze diff against every category
• Post findings (only if breaking) or conclude no issues

Result: No SDK-breaking changes detected.

This PR is docs-only: both commits (99249b3f, f981b3ea) touch a single file, specs/37007-list-server-side-swap/spec.md (+459/-0 total), which is a Spec-Kit specification document. There are no changes to:

• GraphQL schema / graphql.page / graphql.content (G-1, G-2, G-3)
• REST response shapes for /api/v1/nav, /api/v1/content, /api/v1/page/*, or /api/v1/experiments implementation code (R-1) — the spec explicitly states implementation is blocked pending Add pagination, sorting, filtering and permission checks to the Experiments list endpoint #36823 and has not landed in this PR
• UVE/editor postMessage protocol (__DOTCMS_UVE_EVENT__, DotCMSUVEAction) (U-1, U-2)
• SdkVersionWebInterceptor, X-DotCMS-Version/X-DotCMS-Min-SDK headers, or compareVersions() (H-1)

Since the spec itself documents that all new /api/v1/experiments query parameters (created_by, running_from, running_to, etc.) are planned as additive and optional and no implementation code is included, there is nothing here to evaluate against the SDK contract yet. No comment or label added, per instructions (no code changes = no breaking change to flag).

[erickgonzalez]

On-Hold until #36823 gets fixed, since probably needs to be re-written based on those changes.