chore(quantic): creation of the running-quantic-e2e-tests skill

.agents/skills/managing-quantic-components/SKILL.md

@@ -115,11 +115,13 @@ Follow the package split:
 
 Do not duplicate upstream Headless coverage unless the Quantic component adds behavior on top.
 
+Before or after any change to packages/quantic, use the `running-quantic-e2e-tests` skill to set up the scratch orgs, deploy, and run the Playwright specs — even when the change doesn't need a new E2E test, existing coverage for the touched component(s) should still be re-verified.
+
 ### Working Workflow
 
 1. Inspect the target component folder and a similar existing Quantic component before editing.
 2. Keep changes inside `packages/quantic/force-app/main/default/lwc` unless the request also needs examples, community pages, or tests.
-3. If the change needs E2E coverage, update or add the matching example-community component and route assets as needed.
+3. If the change needs E2E coverage, update or add the matching example-community component and route assets as needed. Then follow the `running-quantic-e2e-tests` skill to deploy and run it.
 4. **Before writing any CSS:** go through every style need and verify whether an SLDS utility class satisfies it. Only write custom CSS for styles that SLDS cannot achieve. When replicating a component from another library (e.g. Atomic), do not port its custom CSS directly — re-implement the layout and styling using SLDS classes.
 5. Update JSDoc and metadata consistently with the component's public surface.
 6. Run `pnpm run lint:fix` from `packages/quantic` before considering the work done.

.agents/skills/running-quantic-e2e-tests/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: running-quantic-e2e-tests
+description: Use whenever changing anything in packages/quantic, whether or not new e2e tests are being written — this applies even if you conclude no new e2e coverage is needed, since existing specs still need to be re-verified. Sets up the Salesforce scratch orgs Quantic e2e tests require, deploys local changes to them, and runs the Playwright specs with a fast iteration loop and a full sanity pass. Also use whenever an e2e run fails for reasons that look environmental.
+---
+
+# Running Quantic e2e Tests
+
+Quantic e2e tests run Playwright against real Salesforce scratch orgs hosting the example communities. They are runnable locally.
+
+Every command below runs from `packages/quantic`, except the setup script, which works from anywhere in the repo.
+
+## 1. Ensure the environment
+
+```bash
+./.agents/skills/running-quantic-e2e-tests/scripts/ensure-e2e-orgs.sh
+```
+
+Run this before touching e2e. It is a no-op of a couple of seconds when things are already in place, so there is no reason to skip it.
+
+It verifies two things per org, both required:
+
+| Requirement | Why |
+|---|---|
+| The org exists (`Quantic__LWS_enabled`, `Quantic__LWS_disabled`) | Hosts the example community the tests drive |
+| `.env/<alias>.env` contains `<alias>_URL` | `playwright.config.ts` reads it for `baseURL`. Without it every spec fails as if the tests were broken |
+
+If anything is missing it runs `pnpm run setup:examples`, which creates both scratch orgs, deploys the components and publishes the example communities. That takes several minutes. It then re-verifies and fails loudly.
+
+Exit codes: `0` ready, `1` not ready with the reason, `2` run from outside the repo.
+
+## 2. Iterate on the quick loop
+
+While developing, keep the loop narrow. Deploy only what you changed, and run only the tests that cover it.
+
+**Deploy just the path you touched.** `-d` accepts any path under `force-app`, and a single-component deploy takes seconds where a full deploy takes minutes:
+
+```bash
+sf project deploy start -d ./force-app/main/default/lwc/quanticGeneratedAnswerBody -o Quantic__LWS_enabled
+```
+
+Deploy every path your change touched, not only the component: a new custom label, an example component or an example community page each need their own path deployed before a spec can reach them.
+
+**Run the narrowest useful test.** Start from the specific behaviour you altered, widen as it goes green:
+
+```bash
+# one describe or test title
+npx playwright test quanticLoadMoreResults.e2e.ts --project=LWS-enabled -g "load more button"
+
+# the component's whole spec
+npx playwright test quanticLoadMoreResults.e2e.ts --project=LWS-enabled
+```
+
+One project at a time while iterating. Two projects doubles the runtime for feedback you do not need yet.
+
+## 3. Finish on the slow loop
+
+Once the work is done, run the full pass as a sanity check. Narrow runs prove the change; the full pass proves you broke nothing.
+
+```bash
+pnpm run deploy:lws-enabled
+pnpm run deploy:lws-disabled
+
+npx playwright test          # both projects, whole suite
+```
+
+`pnpm run deploy:lws-*` deploys the main source and the examples together, which also catches anything the targeted deploys missed.
+
+LWS enabled and disabled are genuinely different runtimes. A component that passes in one can fail in the other, so a change is not verified until both are green.
+
+## Troubleshooting
+
+Work down this table before editing test code.
+
+| Symptom | Likely cause |
+|---|---|
+| Every spec fails immediately, no page loads | Missing or empty `.env/<alias>.env`, so `baseURL` is undefined. Re-run the setup script |
+| Page loads but the component is absent | Change not deployed to that org. Deploy its path |
+| Example route 404s | Example component or community page not deployed |
+| Was green, now fails after editing another file | Targeted deploy covered one path but not another you touched |
+| Passes on one project, fails on the other | A real LWS difference, not flakiness |
+| `setup:examples` fails outright | Dev Hub auth expired (`sf org login web`), or the scratch org limit is reached |
+
+A failure that turns out to be environmental is not a test bug. Fix the environment and re-run before concluding anything about the code.

.agents/skills/running-quantic-e2e-tests/scripts/ensure-e2e-orgs.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+#
+# Ensures the two Quantic e2e scratch orgs exist and are usable by Playwright.
+#
+# Checks both orgs and both env files, provisions them with `pnpm run setup:examples`
+# only if something is missing, then re-verifies. Safe to run every time: it is a
+# no-op costing a couple of seconds when the environment is already good, and takes
+# several minutes when it has to provision.
+#
+# Exit codes: 0 ready, 1 still not ready (message says what to fix), 2 wrong directory.
+#
+
+set -uo pipefail
+ORGS="Quantic__LWS_enabled Quantic__LWS_disabled"
+MISSING=""
+
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null) || {
+  echo "FAIL: not inside the repository." >&2
+  exit 2
+}
+quantic_dir="$repo_root/packages/quantic"
+[ -d "$quantic_dir" ] || {
+  echo "FAIL: $quantic_dir not found." >&2
+  exit 2
+}
+cd "$quantic_dir" || exit 2
+
+check_env() {
+  MISSING=""
+
+  orgs_json=$(sf org list --json 2>/dev/null) || {
+    MISSING="salesforce-org-list"
+    return
+  }
+
+  for org_alias in $ORGS; do
+    if ! jq -e --arg alias "$org_alias" \
+      '.result.scratchOrgs[] | select(.alias == $alias and .status == "Active")' \
+      >/dev/null <<<"$orgs_json"; then
+      MISSING="$MISSING org:$org_alias"
+      continue
+    fi
+
+    env_file=".env/${org_alias}.env"
+
+    if [ ! -f "$env_file" ]; then
+      MISSING="$MISSING envfile:$env_file"
+    elif ! grep -q "^${org_alias}_URL=." "$env_file"; then
+      MISSING="$MISSING envvar:${org_alias}_URL"
+    fi
+  done
+
+  MISSING="${MISSING# }"
+}
+
+check_env
+if [ -z "$MISSING" ]; then
+  echo "READY: both orgs exist and both env files have a URL. Nothing to provision."
+  exit 0
+fi
+
+echo "Missing: $MISSING"
+echo "Provisioning with 'pnpm run setup:examples'. This creates both scratch orgs,"
+echo "deploys the components, and publishes the example communities."
+
+if ! pnpm run setup:examples; then
+  echo "FAIL: 'pnpm run setup:examples' exited non-zero. Read its output above." >&2
+  echo "Common causes: expired Dev Hub auth, scratch org limit reached." >&2
+  exit 1
+fi
+
+check_env
+if [ -z "$MISSING" ]; then
+  echo "READY: provisioned and verified."
+  exit 0
+fi
+
+echo "FAIL: still missing after provisioning: $MISSING" >&2
+echo "The setup script reported success but verification disagrees. Do not treat e2e" >&2
+echo "failures as test bugs until this is resolved." >&2
+exit 1