diff --git a/AGENTS.md b/AGENTS.md
index 4a087f78a..70963b493 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,7 +4,7 @@
 
 This is the main orchestrator for AI assistants working on this repository. It routes you to the correct templates and documentation based on the developer's task.
 
-**For every developer request:** (1) Identify task type (A–E below). (2) If the work is in an existing package or widget, load that scope's ai-docs (see [Package and widget ai-docs reference](#package-and-widget-ai-docs-reference)) and follow its AGENTS.md. (3) Open the template for that type and complete its mandatory pre-steps (see [Mandatory pre-steps by task type](#mandatory-pre-steps-by-task-type)). (4) Then follow the rest of this guide and the template.
+**For every developer request:** (1) Identify task type (A–F below). (2) If the work is in an existing package, widget, or test framework scope, load that scope's ai-docs (see [Package and widget ai-docs reference](#package-and-widget-ai-docs-reference)) and follow its AGENTS.md. (3) Open the template for that type and complete its mandatory pre-steps (see [Mandatory pre-steps by task type](#mandatory-pre-steps-by-task-type)). (4) Then follow the rest of this guide and the template.
 
 ---
 
@@ -55,7 +55,13 @@ If the developer's message contains multiple distinct task types (for example, "
 **E. Understanding Architecture**
 - Developer needs to understand how something works
 - **Read:** That scope's `ai-docs/AGENTS.md` (usage) and `ai-docs/ARCHITECTURE.md` (technical details); use [Package and widget ai-docs reference](#package-and-widget-ai-docs-reference) to find the path.
-- **Available for:** station-login, user-state, store, cc-components, cc-widgets, ui-logging, test-fixtures; for task package use per-widget ai-docs (CallControl, IncomingTask, OutdialCall, TaskList).
+- **Available for:** station-login, user-state, store, cc-components, cc-widgets, ui-logging, test-fixtures, playwright; for task package use per-widget ai-docs (CallControl, IncomingTask, OutdialCall, TaskList).
+
+**F. Playwright E2E Test Work**
+- Developer wants to add/update/stabilize Playwright tests, suites, sets, or test framework docs
+- **Route to:** [templates/playwright/00-master.md](./ai-docs/templates/playwright/00-master.md)
+- **Follow:** Playwright template workflow (pre-questions → implementation → validation)
+- **⚠️ MANDATORY FIRST STEP:** Complete pre-questions in [templates/playwright/01-pre-questions.md](./ai-docs/templates/playwright/01-pre-questions.md)
 
 ---
 
@@ -169,6 +175,7 @@ Before generating or changing any code, you MUST complete the **pre-step section
 | **C. Add Feature** | [existing-widget/feature-enhancement.md](./ai-docs/templates/existing-widget/feature-enhancement.md) | [Pre-Enhancement Questions](./ai-docs/templates/existing-widget/feature-enhancement.md) (feature info, requirements, compatibility, design input) |
 | **D. Documentation only** | documentation templates | Optional: confirm scope with developer (no code change) |
 | **E. Understanding** | Package ai-docs | None (read-only) |
+| **F. Playwright E2E Test Work** | [playwright/00-master.md](./ai-docs/templates/playwright/00-master.md) | [Pre-Questions](./ai-docs/templates/playwright/01-pre-questions.md) (scope, scenarios, setup/utilities, stability expectations) |
 
 ---
 
@@ -202,6 +209,7 @@ Before generating or changing any code, you MUST complete the **pre-step section
 | **cc-widgets** | [packages/contact-center/cc-widgets/ai-docs/AGENTS.md](packages/contact-center/cc-widgets/ai-docs/AGENTS.md) | Same folder |
 | **ui-logging** | [packages/contact-center/ui-logging/ai-docs/AGENTS.md](packages/contact-center/ui-logging/ai-docs/AGENTS.md) | Same folder |
 | **samples-cc-react-app** | [widgets-samples/cc/samples-cc-react-app/ai-docs/AGENTS.md](widgets-samples/cc/samples-cc-react-app/ai-docs/AGENTS.md) | Same folder if present |
+| **playwright framework** | [playwright/ai-docs/AGENTS.md](playwright/ai-docs/AGENTS.md) | [playwright/ai-docs/ARCHITECTURE.md](playwright/ai-docs/ARCHITECTURE.md) |
 
 **Task package note:** The task package has multiple widgets (CallControl, IncomingTask, OutdialCall, TaskList). When working on one of them, use that widget's ai-docs path above, not a generic task path.
 
@@ -212,6 +220,11 @@ Before generating or changing any code, you MUST complete the **pre-step section
 - Find available methods, events, types
 - Check method signatures before using
 
+**If working on Playwright tests/framework:**
+- Read: `playwright/ai-docs/AGENTS.md`
+- Read: `playwright/ai-docs/ARCHITECTURE.md`
+- Use: `ai-docs/templates/playwright/00-master.md` and complete `01-pre-questions.md` before implementation
+
 ---
 
 ## Step 3: SDK API Consultation (Before Code Generation)
@@ -479,6 +492,11 @@ yarn build
 **If architecture changed:**
 - Update: Relevant architecture documentation as needed
 
+**If Playwright E2E framework/docs changed:**
+- Update: `playwright/ai-docs/AGENTS.md`
+- Update: `playwright/ai-docs/ARCHITECTURE.md`
+- Update relevant modules in: `ai-docs/templates/playwright/`
+
 ---
 
 ## Step 7: Validation & Review
diff --git a/ai-docs/README.md b/ai-docs/README.md
index c8a15a21e..67739e788 100644
--- a/ai-docs/README.md
+++ b/ai-docs/README.md
@@ -176,6 +176,7 @@ Widget (Observer) → Custom Hook (Business Logic) → Component (UI) → Store
 
 **Repository Patterns:**
 - `ai-docs/patterns/` - TypeScript, MobX, React, Web Components, Testing patterns
+- `ai-docs/templates/` - Task templates (new widget, bug fix, feature enhancement, documentation, Playwright)
 
 **Component Documentation:**
 - `packages/*/ai-docs/README.md` - API and usage
@@ -199,4 +200,4 @@ See [AGENTS.md](./AGENTS.md) for AI navigation guidance, task-based workflows, a
 
 ---
 
-_Last Updated: 2025-11-23_
+_Last Updated: 2026-03-04_
diff --git a/ai-docs/templates/README.md b/ai-docs/templates/README.md
index d14e2949e..63eff5757 100644
--- a/ai-docs/templates/README.md
+++ b/ai-docs/templates/README.md
@@ -10,7 +10,8 @@ Templates for generating and maintaining contact center widgets and components.
 templates/
 ├── new-widget/          # Widget generation (7 modules)
 ├── existing-widget/     # Bug fixes, features (2 modules)
-└── documentation/       # Documentation generation (2 modules, reusable for all packages)
+├── documentation/       # Documentation generation (2 modules, reusable for all packages)
+└── playwright/          # Playwright E2E templates
 ```
 
 ## Templates
@@ -46,6 +47,17 @@ templates/
 - [create-agent-md.md](./documentation/create-agent-md.md) - Generate AGENTS.md
 - [create-architecture-md.md](./documentation/create-architecture-md.md) - Generate ARCHITECTURE.md
 
+### 4. Playwright E2E Work
+
+**Directory:** [playwright/](./playwright/)
+
+**Modules:**
+- [00-master.md](./playwright/00-master.md) - Orchestrator and workflow
+- [01-pre-questions.md](./playwright/01-pre-questions.md) - Mandatory intake
+- [02-test-implementation.md](./playwright/02-test-implementation.md) - Suites/tests/sets implementation
+- [03-framework-and-doc-updates.md](./playwright/03-framework-and-doc-updates.md) - Shared framework/docs updates
+- [04-validation.md](./playwright/04-validation.md) - Validation checklist
+
 ---
 
 ## Usage
@@ -58,6 +70,8 @@ templates/
 
 **Documentation Only:** Use [documentation/](./documentation/) templates
 
+**Playwright E2E Work:** Start with [playwright/00-master.md](./playwright/00-master.md)
+
 ## Pattern References
 
 - [TypeScript Patterns](../patterns/typescript-patterns.md)
@@ -68,4 +82,4 @@ templates/
 
 ---
 
-_Last Updated: 2025-11-26_
+_Last Updated: 2026-03-04_
diff --git a/ai-docs/templates/playwright/00-master.md b/ai-docs/templates/playwright/00-master.md
new file mode 100644
index 000000000..5bf934d82
--- /dev/null
+++ b/ai-docs/templates/playwright/00-master.md
@@ -0,0 +1,59 @@
+# Playwright Test Work - Master Template
+
+## Purpose
+
+Orchestrator for Playwright E2E work in this repository.
+
+---
+
+## Workflow
+
+1. Gather complete requirements -> [01-pre-questions.md](./01-pre-questions.md)
+2. Implement tests/suites/sets -> [02-test-implementation.md](./02-test-implementation.md)
+3. Apply framework updates and documentation alignment -> [03-framework-and-doc-updates.md](./03-framework-and-doc-updates.md)
+4. Validate before completion -> [04-validation.md](./04-validation.md)
+
+Doc alignment is mandatory when any suite/test/set/framework behavior changes.
+
+---
+
+## Task Types
+
+Use one or more values from:
+
+- `new_test_suite`
+- `new_test_file`
+- `add_scenarios_to_existing_test`
+- `update_existing_test_logic`
+- `stabilize_flaky_tests`
+- `add_or_update_user_set`
+- `add_or_update_utils`
+- `add_or_update_test_manager`
+- `add_or_update_constants`
+- `add_or_update_global_setup`
+- `update_playwright_docs`
+
+---
+
+## Current Set-to-Suite Mapping
+
+Use `playwright/test-data.ts` as the source of truth for current set/suite mappings.
+
+Guidance:
+- Read existing `USER_SETS` entries before proposing changes
+- Reuse an existing set when possible
+- Create a new set only when required by scenario isolation, credentials, or participant count
+- Keep set design generic so any scenario can be added via requirements intake
+
+---
+
+## Execution Guidance
+
+- Always start with [01-pre-questions.md](./01-pre-questions.md).
+- Keep implementations aligned with current framework files (`playwright/suites`, `playwright/tests`, `playwright/Utils`, `playwright/test-manager.ts`, `playwright/test-data.ts`, `playwright/constants.ts`, `playwright/global.setup.ts`, `playwright.config.ts`).
+- For all test/suite/set/framework changes, update `playwright/ai-docs/AGENTS.md` and/or `playwright/ai-docs/ARCHITECTURE.md` as part of the same task.
+- End with [04-validation.md](./04-validation.md).
+
+---
+
+_Last Updated: 2026-03-05_
diff --git a/ai-docs/templates/playwright/01-pre-questions.md b/ai-docs/templates/playwright/01-pre-questions.md
new file mode 100644
index 000000000..47d9b1433
--- /dev/null
+++ b/ai-docs/templates/playwright/01-pre-questions.md
@@ -0,0 +1,102 @@
+# Playwright Pre-Questions
+
+## Purpose
+
+Mandatory intake checklist to ensure the user provides complete implementation details before Playwright changes.
+
+---
+
+## Core Principles
+
+### 1. Root Cause Analysis Over Symptomatic Fixes
+- **NEVER** increase timeouts as a first response to flaky tests
+- **ALWAYS** investigate WHY a test is failing before applying fixes
+- Timeouts mask underlying issues (race conditions, incorrect selectors, state leakage)
+- Document the specific reason if timeout increases are necessary
+
+### 2. No Lazy Reasoning
+- **NEVER** assume "it probably works this way" - verify by reading code or testing
+- **NEVER** copy-paste patterns without understanding them
+- **NEVER** skip edge cases or error handling
+- **ALWAYS** ask clarifying questions when requirements are unclear
+
+### 3. Timeout Justification Required
+- Default timeouts should be sufficient for most operations
+- When increasing timeouts, document:
+  - What specific operation needs more time
+  - Why this operation requires more time (measured/observed duration)
+  - Why the operation cannot be optimized instead
+- Example GOOD reason: "Widget initialization requires loading external config (observed 15-20s in production)"
+- Example BAD reason: "Test was flaky, increased timeout to make it pass"
+
+### 4. Requirements Gathering First
+- Use questionnaire-driven approach
+- Understand full scope before implementation
+- Identify edge cases and error scenarios upfront
+- Don't start coding until requirements are clear
+
+---
+
+## Required Questions
+
+### 1. Task Scope
+
+- What exactly should be changed? (one sentence)
+- Is this a new suite, new test, update, or flaky-test stabilization?
+- Which current suite is impacted? (`playwright/suites/*.spec.ts`)
+
+### 2. Coverage Details
+
+- Exact scenarios to add/update (list each scenario title)
+- Expected assertions for each scenario
+- Out-of-scope scenarios
+
+### 3. Execution Target
+
+- Which set(s) should run this? (`SET_1`..`SET_N` or new set)
+- If new set is needed:
+  - What suite filename should `TEST_SUITE` map to?
+  - How many agents are required? (1-4)
+  - What entry points/queues/URLs are needed?
+
+### 4. Data and Environment
+
+- Required env keys (entry points, queue, chat URL, dial number, etc.)
+- How many agents are needed? (1-4)
+- Which roles are needed? (Agent1/Agent2/Agent3/Agent4/caller/extension/multi-session)
+- Any OAuth or token-related constraints?
+- Are there specific user credentials or permissions required?
+
+### 5. Setup and Utilities
+
+- Preferred `TestManager` setup method (if known)
+- Can existing `Utils/*` be reused, or is a new helper needed?
+
+### 6. Stability Expectations
+
+- Known flaky points today and their root causes (if known)
+- Have existing flaky tests been investigated for root cause?
+- Are there specific operations that legitimately require longer timeouts? (with justification)
+- What cleanup is required? (wrapup/end-state/agent cleanup)
+- Are there race conditions or state dependencies to address?
+
+**Important:** If user mentions timeout issues:
+1. First investigate: console logs, network traces, application state
+2. Identify root cause: race condition? slow operation? incorrect selector?
+3. Fix root cause: add proper state checks, optimize operation, fix selector
+4. Only increase timeout if justified and documented
+
+### 7. Documentation Expectations
+
+- Should `playwright/ai-docs/AGENTS.md` be updated?
+- Should `playwright/ai-docs/ARCHITECTURE.md` be updated?
+
+---
+
+## Completion Gate
+
+Do not start implementation until required questions are answered or explicitly assumed and documented.
+
+---
+
+_Last Updated: 2026-03-04_
diff --git a/ai-docs/templates/playwright/02-test-implementation.md b/ai-docs/templates/playwright/02-test-implementation.md
new file mode 100644
index 000000000..ae972e8dc
--- /dev/null
+++ b/ai-docs/templates/playwright/02-test-implementation.md
@@ -0,0 +1,63 @@
+# Playwright Test Implementation
+
+## Purpose
+
+Implement new or updated Playwright suites/tests/sets using current framework conventions.
+
+---
+
+## Implementation Paths
+
+### A. New Suite
+
+- Add `playwright/suites/<name>-tests.spec.ts`
+- Import one or more test factories from `playwright/tests/`
+- Wire `TEST_SUITE` in `playwright/test-data.ts`
+
+### B. New Test File
+
+- Add `playwright/tests/<feature>-test.spec.ts`
+- Export default factory: `create...Tests`
+- Register factory in target suite with `test.describe(...)`
+
+### C. Update Existing Tests
+
+- Update scenario logic in `playwright/tests/*.spec.ts`
+- Preserve existing factory export shape
+- Keep deterministic setup and cleanup
+
+### D. Add/Update User Set
+
+- Update `USER_SETS` in `playwright/test-data.ts`
+- Provide required set fields:
+  - `AGENTS`
+  - `QUEUE_NAME`
+  - `CHAT_URL`
+  - `EMAIL_ENTRY_POINT`
+  - `ENTRY_POINT`
+  - `TEST_SUITE`
+
+---
+
+## Required Patterns
+
+- Use `TestManager` convenience setup methods when possible
+- Reuse `playwright/Utils/*.ts` before adding new helper logic
+- Use shared constants from `playwright/constants.ts`
+- Keep set-scoped env access via `${testManager.projectName}_...`
+- For flaky test fixes, record root cause and update docs if behavior/expectations changed
+
+---
+
+## Done Criteria
+
+- [ ] Suite/test wiring complete
+- [ ] Set mapping correct (if changed)
+- [ ] Cleanup path present for new/changed scenarios
+- [ ] `playwright/ai-docs/AGENTS.md` baseline updated (if suites/sets/workflow changed)
+- [ ] `playwright/ai-docs/ARCHITECTURE.md` topology/mapping/runtime docs updated (if files/sets/framework behavior changed)
+- [ ] Fix/stabilization changes include a doc update loop when behavior or constraints changed
+
+---
+
+_Last Updated: 2026-03-05_
diff --git a/ai-docs/templates/playwright/03-framework-and-doc-updates.md b/ai-docs/templates/playwright/03-framework-and-doc-updates.md
new file mode 100644
index 000000000..c17568d60
--- /dev/null
+++ b/ai-docs/templates/playwright/03-framework-and-doc-updates.md
@@ -0,0 +1,42 @@
+# Playwright Framework and Docs Updates
+
+## Purpose
+
+Apply shared framework updates and keep Playwright docs aligned in the same task.
+
+---
+
+## Framework Files
+
+Update these as needed for reusable behavior changes:
+
+- `playwright/Utils/*.ts`
+- `playwright/test-manager.ts`
+- `playwright/constants.ts`
+- `playwright/global.setup.ts`
+- `playwright.config.ts`
+
+---
+
+## Doc Files (Required Alignment)
+
+- `playwright/ai-docs/AGENTS.md`
+- `playwright/ai-docs/ARCHITECTURE.md`
+
+`playwright/ai-docs/ARCHITECTURE.md` is the single source of truth for framework internals and scenario-level technical reference.
+
+If a task adds/changes suites, tests, sets, setup flows, runtime flags, or stability constraints, doc updates are mandatory.
+
+---
+
+## Checklist
+
+- [ ] Shared changes are reusable and not test-case specific
+- [ ] Existing tests remain backward compatible or intentionally migrated
+- [ ] AGENTS baseline reflects current suites/sets/workflow
+- [ ] ARCHITECTURE topology/mapping/runtime sections match current code
+- [ ] No references to non-existent files/suites/sets
+
+---
+
+_Last Updated: 2026-03-05_
diff --git a/ai-docs/templates/playwright/04-validation.md b/ai-docs/templates/playwright/04-validation.md
new file mode 100644
index 000000000..d137a5c0a
--- /dev/null
+++ b/ai-docs/templates/playwright/04-validation.md
@@ -0,0 +1,26 @@
+# Playwright Validation
+
+## Commands
+
+```bash
+# list projects/tests
+yarn playwright test --config=playwright.config.ts --list
+
+# run target suite
+yarn test:e2e playwright/suites/<suite-file>.spec.ts
+
+# run target set
+yarn test:e2e --project=SET_1
+```
+
+## Checklist
+
+- [ ] Tests are mapped to correct suite/set
+- [ ] Setup/cleanup is deterministic
+- [ ] AGENTS.md baseline matches actual suites/sets/workflow
+- [ ] ARCHITECTURE.md file topology and set/suite/test mapping matches actual files
+- [ ] No stale references in docs/templates
+
+---
+
+_Last Updated: 2026-03-05_
diff --git a/ai-docs/templates/playwright/README.md b/ai-docs/templates/playwright/README.md
new file mode 100644
index 000000000..ce2c31490
--- /dev/null
+++ b/ai-docs/templates/playwright/README.md
@@ -0,0 +1,28 @@
+# Playwright Templates
+
+## Purpose
+
+Simplified modular templates for Playwright E2E work.
+
+## Structure
+
+```text
+playwright/
+├── 00-master.md                    # Orchestrator and workflow
+├── 01-pre-questions.md             # Mandatory intake questions
+├── 02-test-implementation.md       # Suites/tests/sets implementation
+├── 03-framework-and-doc-updates.md # Shared framework and docs updates
+└── 04-validation.md                # Validation checklist
+```
+
+## Usage
+
+1. Start with [00-master.md](./00-master.md).
+2. Complete [01-pre-questions.md](./01-pre-questions.md) before code changes.
+3. Implement using [02-test-implementation.md](./02-test-implementation.md).
+4. If needed, apply [03-framework-and-doc-updates.md](./03-framework-and-doc-updates.md).
+5. Finish with [04-validation.md](./04-validation.md).
+
+---
+
+_Last Updated: 2026-02-18_
diff --git a/playwright/ai-docs/AGENTS.md b/playwright/ai-docs/AGENTS.md
new file mode 100644
index 000000000..1e956e047
--- /dev/null
+++ b/playwright/ai-docs/AGENTS.md
@@ -0,0 +1,108 @@
+# Playwright E2E Testing Framework
+
+## Overview
+
+The `playwright/` directory contains the end-to-end testing framework for Contact Center widgets.
+
+This guide is for implementation workflow and usage. For technical internals, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+---
+
+## Scope
+
+Use this guide when the request involves:
+
+- adding or updating Playwright scenarios
+- fixing flaky E2E tests
+- creating or updating suite wiring
+- adding a new test set in `playwright/test-data.ts`
+- updating shared framework behavior (`test-manager`, `Utils`, `global.setup`, `constants`)
+- updating Playwright documentation
+
+---
+
+## Current Baseline (Aligns to `next`)
+
+Current test sets and suites come from `playwright/test-data.ts`.
+
+At the time of this doc update, the baseline suites are:
+
+- `digital-incoming-task-tests.spec.ts`
+- `task-list-multi-session-tests.spec.ts`
+- `station-login-user-state-tests.spec.ts`
+- `basic-advanced-task-controls-tests.spec.ts`
+- `advanced-task-controls-tests.spec.ts`
+- `dial-number-tests.spec.ts`
+
+Do not assume additional sets/suites exist unless they are present in code.
+
+---
+
+## Required Workflow
+
+1. Start with root orchestrator: `AGENTS.md`
+2. For Playwright tasks, run template flow from:
+   - `ai-docs/templates/playwright/00-master.md`
+3. Complete pre-questions first:
+   - `ai-docs/templates/playwright/01-pre-questions.md`
+4. Implement via:
+   - `ai-docs/templates/playwright/02-test-implementation.md`
+5. If framework/docs must change, use:
+   - `ai-docs/templates/playwright/03-framework-and-doc-updates.md`
+6. Validate with:
+   - `ai-docs/templates/playwright/04-validation.md`
+
+Do not start coding before pre-questions are answered or assumptions are explicitly documented.
+
+---
+
+## New Scenario Requests
+
+New E2E scenario generation is supported through requirements intake plus framework updates.
+
+When asked to generate new Playwright scenarios:
+
+1. Collect full requirements via the Playwright questionnaire
+2. Decide whether existing sets/framework are sufficient
+3. If not sufficient, include required framework changes in the same task:
+   - `playwright/test-data.ts` (set mapping)
+   - `playwright/test-manager.ts` (setup/cleanup capability)
+   - `playwright/global.setup.ts` (env/token flow)
+   - `playwright/constants.ts` and `playwright/Utils/*` as needed
+4. Add suite/test files and wire them through `TEST_SUITE`
+5. Update this doc and `ARCHITECTURE.md`
+
+This keeps docs generic while still enabling scenario generation from questionnaire answers.
+
+---
+
+## Common Commands
+
+```bash
+# Run all E2E tests
+yarn test:e2e
+
+# List projects/tests
+yarn playwright test --config=playwright.config.ts --list
+
+# Run a suite
+yarn test:e2e playwright/suites/<suite-file>.spec.ts
+
+# Run a set/project
+yarn test:e2e --project=SET_1
+```
+
+---
+
+## Documentation Rules
+
+When Playwright behavior changes:
+
+- Update this file for runbook and workflow expectations
+- Update `playwright/ai-docs/ARCHITECTURE.md` for technical architecture changes
+- Keep docs aligned with actual files in `playwright/`
+- Avoid hardcoding future/nonexistent sets or suite names
+
+---
+
+_Last Updated: 2026-03-04_
diff --git a/playwright/ai-docs/ARCHITECTURE.md b/playwright/ai-docs/ARCHITECTURE.md
new file mode 100644
index 000000000..f08a51938
--- /dev/null
+++ b/playwright/ai-docs/ARCHITECTURE.md
@@ -0,0 +1,364 @@
+# Playwright E2E Framework — Architecture
+
+## Purpose
+
+Technical reference for Playwright framework structure, runtime data flow, and extension points.
+
+---
+
+## Layering
+
+```text
+Playwright Project (Set)
+  -> Suite (playwright/suites/*.spec.ts)
+    -> Test Factory (playwright/tests/*.spec.ts)
+      -> Utils + TestManager + Constants
+        -> Browser + Widgets + SDK-backed behavior
+```
+
+---
+
+## Source of Truth
+
+- Set definitions and suite mapping: `playwright/test-data.ts` (`USER_SETS`)
+- Project generation and browser/runtime config: `playwright.config.ts`
+- Runtime setup/teardown orchestration: `playwright/test-manager.ts`
+- Shared test operations: `playwright/Utils/*.ts`
+- Shared constants/types/timeouts: `playwright/constants.ts`
+- OAuth + set-scoped env expansion: `playwright/global.setup.ts`
+
+---
+
+## Current File Topology (Baseline)
+
+```text
+playwright/
+├── suites/
+│   ├── digital-incoming-task-tests.spec.ts
+│   ├── task-list-multi-session-tests.spec.ts
+│   ├── station-login-user-state-tests.spec.ts
+│   ├── basic-advanced-task-controls-tests.spec.ts
+│   ├── advanced-task-controls-tests.spec.ts
+│   └── dial-number-tests.spec.ts
+├── tests/
+│   ├── digital-incoming-task-and-task-controls.spec.ts
+│   ├── incoming-task-and-controls-multi-session.spec.ts
+│   ├── station-login-test.spec.ts
+│   ├── user-state-test.spec.ts
+│   ├── incoming-telephony-task-test.spec.ts
+│   ├── basic-task-controls-test.spec.ts
+│   ├── advanced-task-controls-test.spec.ts
+│   ├── advance-task-control-combinations-test.spec.ts
+│   ├── dial-number-task-control-test.spec.ts
+│   └── tasklist-test.spec.ts
+├── Utils/
+│   ├── initUtils.ts
+│   ├── helperUtils.ts
+│   ├── incomingTaskUtils.ts
+│   ├── stationLoginUtils.ts
+│   ├── userStateUtils.ts
+│   ├── taskControlUtils.ts
+│   ├── advancedTaskControlUtils.ts
+│   └── wrapupUtils.ts
+├── test-manager.ts
+├── test-data.ts
+├── constants.ts
+├── global.setup.ts
+└── ai-docs/
+    ├── AGENTS.md
+    └── ARCHITECTURE.md
+```
+
+Keep this section aligned to real repository contents.
+
+---
+
+## Set -> Suite -> Test Mapping
+
+| Set | Suite File (`TEST_SUITE`) | Test Files Imported By Suite |
+| --- | --- | --- |
+| `SET_1` | `digital-incoming-task-tests.spec.ts` | `digital-incoming-task-and-task-controls.spec.ts`, `dial-number-task-control-test.spec.ts` |
+| `SET_2` | `task-list-multi-session-tests.spec.ts` | `incoming-task-and-controls-multi-session.spec.ts`, `tasklist-test.spec.ts` |
+| `SET_3` | `station-login-user-state-tests.spec.ts` | `station-login-test.spec.ts`, `user-state-test.spec.ts`, `incoming-telephony-task-test.spec.ts` |
+| `SET_4` | `basic-advanced-task-controls-tests.spec.ts` | `basic-task-controls-test.spec.ts`, `advance-task-control-combinations-test.spec.ts` |
+| `SET_5` | `advanced-task-controls-tests.spec.ts` | `advanced-task-controls-test.spec.ts` |
+| `SET_6` | `dial-number-tests.spec.ts` | `dial-number-task-control-test.spec.ts` |
+
+Use this mapping to decide where new tests should be added and wired.
+
+---
+
+## Dynamic Project Generation
+
+`playwright.config.ts` creates Playwright projects from `USER_SETS`:
+
+- Project name: set key (`SET_X`)
+- Suite binding: `testMatch = **/suites/${TEST_SUITE}`
+- Worker count: `Object.keys(USER_SETS).length`
+- Global timeout: `180000`
+- Per-project retries: `1`
+
+Any set added to `USER_SETS` becomes runnable through this model.
+
+### System Under Test
+
+The E2E tests validate Contact Center widgets running in `samples-cc-react-app` served at `http://localhost:3000`.
+
+`playwright.config.ts` boots the app using:
+
+```typescript
+webServer: {
+  command: 'yarn workspace samples-cc-react-app serve',
+  url: 'http://localhost:3000',
+}
+```
+
+Each generated set project uses Chrome launch flags required for telephony/WebRTC automation:
+
+- `--use-fake-ui-for-media-stream`
+- `--use-fake-device-for-media-stream`
+- `--use-file-for-fake-audio-capture=<repo>/playwright/wav/dummyAudio.wav`
+- `--remote-debugging-port=${9221 + index}` (unique port per set)
+
+These flags are part of baseline runtime behavior and should be preserved unless intentionally changed.
+
+---
+
+## Runtime Data Flow
+
+`global.setup.ts`:
+
+1. Expands `USER_SETS` into set-scoped env keys (`<SET>_...`)
+2. Fetches OAuth tokens for agents in each set
+3. Writes token/env updates to `.env`
+
+Test files:
+
+1. Read Playwright project name via `test.info().project.name`
+2. Instantiate `new TestManager(projectName)`
+
+`test-manager.ts`:
+
+1. Receives the set key via constructor (`projectName`)
+2. Resolves set-scoped env values using that project key
+3. Creates required contexts/pages and performs login/widget initialization
+4. Handles soft cleanup (`softCleanup`) and full cleanup (`cleanup`)
+
+---
+
+## TestManager
+
+`TestManager` is the setup/teardown orchestrator used across suites.
+
+### Constructor
+
+```typescript
+new TestManager(projectName: string, maxRetries?: number)
+```
+
+- `projectName`: set key (for example, `SET_1`) used to resolve env values like `${projectName}_AGENT1_ACCESS_TOKEN`
+- `maxRetries`: optional retry count (default from `DEFAULT_MAX_RETRIES`)
+
+### SetupConfig (Universal setup)
+
+`setup(browser, config)` accepts:
+
+```typescript
+interface SetupConfig {
+  needsAgent1?: boolean; // default: true
+  needsAgent2?: boolean; // default: false
+  needsCaller?: boolean; // default: false
+  needsExtension?: boolean; // default: false
+  needsChat?: boolean; // default: false
+  needsMultiSession?: boolean; // default: false
+  agent1LoginMode?: LoginMode; // default: LOGIN_MODE.DESKTOP
+  enableConsoleLogging?: boolean; // default: true
+  enableAdvancedLogging?: boolean; // default: false
+  needDialNumberLogin?: boolean; // default: false
+}
+```
+
+### Page Properties
+
+When enabled by setup config/method, these page properties are created and available:
+
+- `agent1Page`
+- `agent2Page`
+- `callerPage`
+- `agent1ExtensionPage`
+- `chatPage`
+- `multiSessionAgent1Page`
+- `dialNumberPage`
+
+### Universal Setup Flow (3 phases)
+
+`setup()` runs a three-phase flow:
+
+1. Create required browser contexts/pages in parallel (`createContextsForConfig`)
+2. Run independent login + widget setup in parallel (`createSetupPromises` + optional multi-session flow)
+3. Register console logging handlers (`setupConsoleLogging`)
+
+### Convenience Methods
+
+| Method | Behavior |
+| --- | --- |
+| `basicSetup()` | Calls `setup()` with desktop agent1 defaults |
+| `setupForAdvancedTaskControls()` | Calls `setup()` with agent1+agent2+caller+extension and advanced logging |
+| `setupForAdvancedCombinations()` | Calls `setup()` with agent1+agent2+caller and advanced logging |
+| `setupForDialNumber()` | Calls `setup()` with dial-number login enabled |
+| `setupForIncomingTaskDesktop()` | Calls `setup()` for desktop incoming-task flow |
+| `setupForIncomingTaskExtension()` | Calls `setup()` for extension incoming-task flow |
+| `setupForIncomingTaskMultiSession()` | Calls `setup()` for multi-session incoming-task flow |
+| `setupForStationLogin()` | Custom path (does not call `setup()`), purpose-built station-login + multi-login bootstrap |
+| `setupMultiSessionPage()` | Targeted helper to initialize only multi-session page when needed |
+
+### Cleanup
+
+- `softCleanup()`:
+  - Handles stray tasks only (`handleStrayTasks`)
+  - Intended for between-file cleanup via `afterAll`
+- `cleanup()`:
+  - Runs `softCleanup()` first
+  - Performs station logout where applicable
+  - Closes all created pages/contexts
+  - Intended for end-of-suite full cleanup
+
+---
+
+## Utils Reference
+
+| File | Key Exports | Purpose |
+| --- | --- | --- |
+| `initUtils.ts` | `loginViaAccessToken`, `oauthLogin`, `enableAllWidgets`, `enableMultiLogin`, `initialiseWidgets`, `agentRelogin`, `setupMultiLoginPage` | Auth/bootstrap/widget init helpers |
+| `stationLoginUtils.ts` | `desktopLogin`, `extensionLogin`, `dialLogin`, `telephonyLogin`, `stationLogout`, `verifyLoginMode`, `ensureUserStateVisible` | Station login/logout validation for Desktop/Extension/Dial Number |
+| `userStateUtils.ts` | `changeUserState`, `getCurrentState`, `verifyCurrentState`, `getStateElapsedTime`, `validateConsoleStateChange`, `checkCallbackSequence` | User-state actions and console/state validation |
+| `taskControlUtils.ts` | `holdCallToggle`, `recordCallToggle`, `endTask`, `verifyHoldTimer`, `verifyHoldButtonIcon`, `verifyRecordButtonIcon`, `setupConsoleLogging`, `verifyHoldLogs`, `verifyRecordingLogs`, `verifyEndLogs`, `verifyRemoteAudioTracks` | Basic call control actions + callback/event log assertions |
+| `advancedTaskControlUtils.ts` | `consultOrTransfer`, `cancelConsult`, `setupAdvancedConsoleLogging`, `verifyTransferSuccessLogs`, `verifyConsultStartSuccessLogs`, `verifyConsultEndSuccessLogs`, `verifyConsultTransferredLogs` | Consult/transfer operations + advanced callback/event log assertions |
+| `incomingTaskUtils.ts` | `createCallTask`, `createChatTask`, `createEmailTask`, `waitForIncomingTask`, `acceptIncomingTask`, `declineIncomingTask`, `acceptExtensionCall`, `loginExtension`, `submitRonaPopup` | Incoming task creation/acceptance/decline and extension helpers |
+| `wrapupUtils.ts` | `submitWrapup` | Wrapup submission |
+| `helperUtils.ts` | `handleStrayTasks`, `pageSetup`, `waitForState`, `waitForStateLogs`, `waitForWebSocketDisconnection`, `waitForWebSocketReconnection`, `clearPendingCallAndWrapup`, `dismissOverlays` | Shared setup/cleanup/state polling/network-watch helpers |
+
+Use existing helpers first; add new utilities only when behavior is not already covered.
+
+---
+
+## Constants Reference
+
+### Key Enums/Objects
+
+| Constant | Values (Current) | Used For |
+| --- | --- | --- |
+| `USER_STATES` | `MEETING`, `AVAILABLE`, `LUNCH` (`Lunch Break`), `RONA`, `ENGAGED`, `AGENT_DECLINED` | Agent state change/validation |
+| `LOGIN_MODE` | `DESKTOP` (`Desktop`), `EXTENSION` (`Extension`), `DIAL_NUMBER` (`Dial Number`) | Station login mode selection |
+| `PAGE_TYPES` | `AGENT1`, `AGENT2`, `CALLER`, `EXTENSION`, `CHAT`, `MULTI_SESSION`, `DIAL_NUMBER` | TestManager page/context identity |
+| `TASK_TYPES` | `CALL`, `CHAT`, `EMAIL`, `SOCIAL` | Incoming task typing |
+| `WRAPUP_REASONS` | `SALE`, `RESOLVED` | Wrapup flow |
+| `RONA_OPTIONS` | `AVAILABLE`, `IDLE` | RONA popup next-state selection |
+| `CONSOLE_PATTERNS` | `SDK_STATE_CHANGE_SUCCESS`, `ON_STATE_CHANGE_REGEX`, `ON_STATE_CHANGE_KEYWORDS` | State-change console pattern matching |
+
+### Timeout Hierarchy
+
+| Constant | Value | Typical Use |
+| --- | --- | --- |
+| `DROPDOWN_SETTLE_TIMEOUT` | `200` ms | Dropdown animation settle |
+| `UI_SETTLE_TIMEOUT` | `2000` ms | Generic UI settle |
+| `DEFAULT_TIMEOUT` | `5000` ms | Default visibility/check timeout |
+| `AWAIT_TIMEOUT` | `10000` ms | Standard element interactions |
+| `WRAPUP_TIMEOUT` | `15000` ms | Wrapup UI timing |
+| `FORM_FIELD_TIMEOUT` | `20000` ms | Popover/form field loading |
+| `OPERATION_TIMEOUT` | `30000` ms | Longer user operations (for example logout checks) |
+| `EXTENSION_REGISTRATION_TIMEOUT` | `40000` ms | Extension registration waits |
+| `NETWORK_OPERATION_TIMEOUT` | `40000` ms | Network-dependent operations |
+| `WIDGET_INIT_TIMEOUT` | `50000` ms | Widget initialization |
+| `CHAT_LAUNCHER_TIMEOUT` | `60000` ms | Chat launcher iframe loading |
+| `ACCEPT_TASK_TIMEOUT` | `60000` ms | Incoming-task acceptance waits |
+
+Choose the smallest fitting timeout and document reasons for any increases.
+
+---
+
+## Console Log Verification Pattern
+
+Console log monitoring is a core assertion pattern in this framework.
+
+### 1. Setup handlers
+
+- Basic controls: `setupConsoleLogging(page)`
+- Advanced controls: `setupAdvancedConsoleLogging(page)`
+
+These register `page.on('console', ...)` handlers and capture only relevant SDK/callback log messages.
+
+### 2. Captured event categories
+
+Basic controls (`taskControlUtils.ts`):
+
+- `WXCC_SDK_TASK_HOLD_SUCCESS` / `WXCC_SDK_TASK_RESUME_SUCCESS`
+- `WXCC_SDK_TASK_PAUSE_RECORDING_SUCCESS` / `WXCC_SDK_TASK_RESUME_RECORDING_SUCCESS`
+- `onHoldResume invoked` / `onRecordingToggle invoked` / `onEnd invoked`
+
+Advanced controls (`advancedTaskControlUtils.ts`):
+
+- `WXCC_SDK_TASK_TRANSFER_SUCCESS`
+- `WXCC_SDK_TASK_CONSULT_START_SUCCESS`
+- `WXCC_SDK_TASK_CONSULT_END_SUCCESS`
+- `AgentConsultTransferred`
+- `onTransfer invoked` / `onConsult invoked` / `onEnd invoked`
+
+State changes (`userStateUtils.ts` + `constants.ts`):
+
+- `WXCC_SDK_AGENT_STATE_CHANGE_SUCCESS`
+- `onStateChange invoked with state name: <stateName>`
+
+### 3. Verification helpers
+
+- Basic: `verifyHoldLogs`, `verifyRecordingLogs`, `verifyEndLogs`
+- Advanced: `verifyTransferSuccessLogs`, `verifyConsultStartSuccessLogs`, `verifyConsultEndSuccessLogs`, `verifyConsultTransferredLogs`
+- State: `validateConsoleStateChange`, `checkCallbackSequence`
+
+### 4. Sequence validation
+
+`checkCallbackSequence()` verifies ordering for state changes:
+
+1. SDK success log is present
+2. `onStateChange` callback log is present
+3. Callback occurs after SDK success
+4. Logged state value matches expected state
+
+Use this pattern when assertions depend on callback/API event ordering.
+
+---
+
+## Extension Points
+
+When adding a scenario family or changing framework behavior, update in this order:
+
+1. `playwright/tests/*.spec.ts` (test factory logic)
+2. `playwright/suites/*.spec.ts` (suite composition)
+3. `playwright/test-data.ts` (set mapping + set data)
+4. `playwright/test-manager.ts` and/or `playwright/Utils/*.ts` (shared setup/ops)
+5. `playwright/global.setup.ts` and/or `playwright.config.ts` (env/runtime)
+6. `playwright/ai-docs/AGENTS.md` and this file to match final implementation
+
+Do not document future files/sets before they exist in code.
+
+---
+
+## Stability Principles
+
+- Prefer explicit state assertions over blind waits
+- Fix root causes before increasing timeouts
+- Keep setup and cleanup deterministic
+- Reuse existing utilities to avoid divergent selectors/flows
+- Keep tests independently runnable by set/suite
+
+---
+
+## Related
+
+- Workflow/runbook: [./AGENTS.md](./AGENTS.md)
+- Framework overview: [../README.md](../README.md)
+- Playwright templates: [../../ai-docs/templates/playwright/00-master.md](../../ai-docs/templates/playwright/00-master.md)
+
+---
+
+_Last Updated: 2026-03-05_