@webex/contact-center 3.12.0-next.9 → 3.12.0-next.91

package/AGENTS.md

@@ -0,0 +1,94 @@
+# AGENTS.md — @webex/contact-center
+
+> Read first. Next: [`SPEC_INDEX.md`](ai-docs/SPEC_INDEX.md) · [`ARCHITECTURE.md`](ai-docs/ARCHITECTURE.md). Load the target module spec on demand.
+
+## Repo Overview
+
+`@webex/contact-center` is a published Webex SDK plugin for agent registration, configuration, realtime events, task/call control, data lookup, and telemetry.
+
+**What it is:**
+- A TypeScript SDK package embedded in the Webex SDK host.
+- A client of Webex Contact Center REST, WebSocket, calling, and metrics services.
+
+**What it is NOT:**
+- It is not a standalone backend and owns no durable datastore.
+- It does not render a UI; it exposes state and UI-control contracts to host applications.
+
+## Tech Stack
+
+- TypeScript 5.4, Node.js 22.14 for workspace development (published package engine floor: Node >=20.x), Yarn 3.4.1, WebexPlugin, EventEmitter, XState 5, WebSocket/WebRTC.
+- Jest 27 with 85% global branch/function/line/statement thresholds.
+
+## Architecture
+
+```text
+Host Webex SDK → ContactCenter plugin → Services/Task/Metrics → REST + WebSocket + WebRTC backends
+```
+
+→ Full architecture: **[ai-docs/ARCHITECTURE.md](./ai-docs/ARCHITECTURE.md)**
+
+## Module / Package Structure
+
+```text
+src/                                  public plugin/API orchestration
+src/metrics/                          telemetry
+src/services/                         service composition and integrations
+src/services/{agent,config,core}/     agent, profile, and transport capabilities
+src/services/task/                    task/call lifecycle
+src/services/task/state-machine/      typed XState lifecycle engine
+src/utils/                            pagination/page cache contracts
+```
+
+→ Router: **[ai-docs/SPEC_INDEX.md](./ai-docs/SPEC_INDEX.md)**
+
+## Critical Rules
+
+1. Code and tests are the behavioral referee; never invent APIs, paths, events, flags, or states.
+2. Ask before coding: present the affected files/contracts and wait for confirmation.
+3. Use LoggerProxy with module/method context; never use console logging in package implementation.
+4. Use MetricsManager timing/tracking patterns without blocking product behavior.
+5. Use typed event constants; preserve `trigger` versus `emit` ownership.
+6. Preserve AQM HTTP-plus-WebSocket correlation, timeout, and recovery semantics.
+7. Update the owning module spec and contract catalog in the same change as behavior.
+8. Run an independent validator runtime for generated or materially changed specs.
+
+## Essential Commands
+
+| Task | Command |
+|---|---|
+| Install | `yarn install` |
+| Build | `yarn workspace @webex/contact-center build:src` |
+| Test | `yarn workspace @webex/contact-center test:unit` |
+| Lint/format | `yarn workspace @webex/contact-center test:style` |
+
+## Developer Workflow
+
+1. Read this file for package rules, then use `ai-docs/SPEC_INDEX.md` to select the owning canonical module `*-spec.md`.
+2. Check the module spec's requirements, public surface, source paths, test evidence, and documented gaps against the relevant code/tests.
+3. Before coding, present the affected files and contracts and wait for confirmation.
+4. Implement the smallest approved change; update the owning module spec, `ai-docs/CONTRACTS.md`, and `.sdd/manifest.json` when public behavior or routing changes.
+5. Run the package commands above plus manifest/conformance checks; materially changed generated specs require validation on the configured independent runtime.
+6. Review the final diff for source/test fidelity, compatibility, secrets, and unrelated files before staging.
+
+## Common Gotchas
+
+1. AQM completion may arrive over WebSocket after an HTTP acknowledgement; do not treat the acknowledgement as completion.
+2. Listener cleanup requires the same function reference used at registration.
+3. Config aggregation is all-or-nothing; returning a partial profile creates inconsistent runtime behavior.
+4. Task transitions must go through typed TaskEvent mapping and guards.
+5. PageCache bypasses search/filter/attributes/sort queries to avoid stale or incorrect reuse.
+
+## Pre-Commit Checklist
+
+- [ ] Unit tests and lint pass; the 85% coverage bar remains satisfied.
+- [ ] Public types/events/methods remain compatible or include a migration plan.
+- [ ] State, error, timeout, and cleanup paths are covered.
+- [ ] Spec/docs and `.sdd/manifest.json` are updated with code changes.
+- [ ] No secrets or sensitive data are committed or logged.
+
+## Strict Compliance Mode (automation)
+
+- Load this file, the router, and only the affected module specs; stop on a blocking contract, security, source-fidelity, or validation finding.
+
+---
+**SDD coverage:** `.sdd/manifest.json` is authoritative; `ai-docs/SPEC_INDEX.md` mirrors it.

package/ai-docs/ARCHITECTURE.md

@@ -0,0 +1,168 @@
+# ARCHITECTURE — @webex/contact-center
+
+> Start here → root [`AGENTS.md`](../AGENTS.md) · router [`SPEC_INDEX.md`](SPEC_INDEX.md). Per-module detail lives in source-local specifications.
+
+## Design Overview
+
+The package is a host-embedded SDK plugin. `ContactCenter` owns the public façade and composes services for configuration, agent requests, tasks/calling, data lookup, realtime events, transport, and metrics. Remote Webex services own durable domain data.
+
+Two interaction styles are deliberate: direct REST for immediate data/configuration responses, and AQM HTTP initiation followed by correlated WebSocket completion for event-driven agent/task operations. Typed events and XState isolate consumers from raw backend messages.
+
+## Component Inventory & Responsibilities
+
+| Component | Responsibility (one line) | Docs |
+|---|---|---|
+| `src` | Own the published Webex Contact Center SDK plugin surface, registration lifecycle, public method delegation, and application-facing event routing. | `ai-docs/contact-center-spec.md` |
+| `src/metrics` | Own timing, taxonomy, queuing, payload preparation, and submission for Contact Center behavioral, operational, and business telemetry. | `src/metrics/ai-docs/metrics-spec.md` |
+| `src/services` | Own composition and bootstrap order for backend request, realtime, data, and WebRTC service collaborators. | `src/services/ai-docs/services-spec.md` |
+| `src/services/agent` | Own agent login, logout, state-change, buddy-agent, device-update, and silent-relogin request contracts. | `src/services/agent/ai-docs/agent-spec.md` |
+| `src/services/config` | Own retrieval and aggregation of remote organization, agent, team, profile, auxiliary-code, dial-plan, and feature configuration. | `src/services/config/ai-docs/config-spec.md` |
+| `src/services/core` | Own authenticated HTTP, realtime WebSocket lifecycle, AQM request correlation, reconnect/keepalive behavior, and shared error normalization. | `src/services/core/ai-docs/core-spec.md` |
+| `src/services/task` | Own task creation, media-specific behavior, call-control operations, lifecycle orchestration, task events, and integration with the task state machine. | `src/services/task/ai-docs/task-spec.md` |
+| `src/services/task/state-machine` | Own deterministic task lifecycle states, transition guards/actions, typed internal events, and state-derived UI-control availability. | `src/services/task/state-machine/ai-docs/task-state-machine-spec.md` |
+| `src/utils` | Own shared pagination contracts and the bounded in-memory page cache used by Contact Center data services. | `src/utils/ai-docs/utils-spec.md` |
+
+## Component Interaction
+
+```mermaid
+flowchart LR
+  Host[Host Webex SDK] --> CC[ContactCenter]
+  CC --> Services
+  CC --> Task
+  CC --> Metrics
+  Services --> Agent
+  Services --> Config
+  Services --> Core
+  Services --> Utils
+  Task --> StateMachine[Task state machine]
+  Services --> REST[WCC REST]
+  Core <--> WS[WCC WebSocket]
+  Task --> Calling[Webex Calling/WebRTC]
+  Metrics --> Telemetry[Webex metrics]
+```
+
+Public calls enter through `src/cc.ts`; direct REST returns through WebexRequest, while AQM operations resolve after matching WebSocket notifications. TaskManager converts backend events to task/state-machine events.
+
+## Execution & Flow
+
+Registration initializes WebexRequest, Services, MetricsManager, WebCallingService, TaskManager, and data services in evidence-backed order. The plugin subscribes to realtime messages, obtains the remote agent profile, routes agent/task events, and tears down listeners/connections on deregistration.
+
+## Dependencies
+
+| Dependency | Type (internal / external / peer) | How used | Failure / version handling |
+|---|---|---|---|
+| `@webex/webex-core` | external / peer | Runtime package dependency | Workspace/declared version; errors propagate through owning module |
+| `@webex/calling` | external / peer | Runtime package dependency | Workspace/declared version; errors propagate through owning module |
+| `@webex/internal-plugin-metrics` | external / peer | Runtime package dependency | Workspace/declared version; errors propagate through owning module |
+| `@webex/internal-plugin-mercury` | external / peer | Runtime package dependency | Workspace/declared version; errors propagate through owning module |
+| `wcc-api-gateway` | external Webex service | Service-catalog identifier resolved through the host Webex SDK; not an npm package dependency | Host service-catalog availability; routing errors propagate through the owning module |
+
+### State Model
+
+- ContactCenter retains agent profile, task collections, WebSocket/reconnect flags, metrics queues/timers, page-cache entries, and task actors in memory.
+- Remote systems remain authoritative for agent/task/configuration records.
+
+## Cross-Cutting Concerns
+
+- **Security:** host-provided credentials and service routing; no tokens/secrets in source or logs; validate public inputs.
+- **Observability:** LoggerProxy context/tracking ids plus MetricsManager success/failure/duration signals and diagnostic log upload.
+
+## Non-Functional Posture
+
+Package compatibility and event-loop safety are primary: published exports/types are semver-sensitive, telemetry is non-blocking, listeners are cleaned up, and reconnect/timeouts are explicit.
+
+## Dependency / Interaction Topology
+
+```mermaid
+flowchart TD
+  CC -->|calls| Services
+  Services -->|REST| Core
+  Core -->|events| CC
+  Core -->|events| Task
+  Task -->|typed events| StateMachine
+  StateMachine -->|actions/UI controls| Task
+```
+
+| From | To | Kind (call / event) | Purpose |
+|---|---|---|---|
+| ContactCenter | Services | call | Backend/config/agent composition |
+| WebSocketManager | ContactCenter/TaskManager/AqmReqs | event | Realtime routing and request completion |
+| Task | Task state machine | call/event | Validate lifecycle transitions and emit task events |
+| Data services | PageCache | call | Bounded pagination reuse |
+
+## Object / Data Ownership
+
+| Domain object | System-of-record (owning component) | Read by |
+|---|---|---|
+| Agent/Profile | Remote WCC services; Config aggregates a local view | ContactCenter, Agent, Task |
+| Task/Interaction | Remote WCC services; Task owns client representation | ContactCenter consumers |
+| Metric event | Metrics module until submission; remote metrics backend after submit | Observability systems |
+| Cached page | Utils PageCache (ephemeral only) | AddressBook, EntryPoint, Queue |
+
+## Caching Catalog
+
+| Cache | Backend | What it holds | TTL | Invalidation trigger |
+|---|---|---|---|---|
+| PageCache | in-memory Map | simple paginated data-service pages | 5 minutes | expiry or explicit clear; parameterized queries bypass |
+
+## Observability Patterns
+
+- **Logging:** LoggerProxy with module/method and tracking/interaction identifiers; no credentials or sensitive payloads.
+- **Metrics:** METRIC_EVENT_NAMES plus behavioral taxonomy and `WXCC_SDK_` operational/business names.
+- **Audit:** no local audit store; remote services own operational records.
+
+## Infrastructure Matrix
+
+| Category | In use | Notes |
+|---|---|---|
+| Datastores | Remote WCC-owned stores | Package owns no durable store. |
+| Messaging / streaming | WebSocket notification and RTD streams | Used for realtime events and AQM completion. |
+| Cloud / platform services | Webex service catalog, WCC APIs, Calling/WebRTC, metrics | Host SDK supplies credentials/routing. |
+
+## Shared / Base Libraries
+
+| Library | What every module inherits from it | Version floor |
+|---|---|---|
+| `@webex/webex-core` | plugin host, request/service routing | workspace version |
+| `@webex/calling` | browser calling and line/call objects | workspace version |
+| LoggerProxy/MetricsManager | package logging and telemetry conventions | package-local |
+
+## Package Map & Inter-Package Dependencies
+
+- Workspace glob: root `package.json` `workspaces`; this scoped package is public and consumes internal/public sibling packages.
+- `@webex/contact-center` depends on core, calling, metrics, mercury, support, authorization, and logger workspace packages; releases use the repository's synchronized package tooling.
+
+## Release & Versioning
+
+- Published through the package's npm publish script to the configured registry. Public exports and declarations follow semver; breaking changes require a major-version consumer transition and changelog entry.
+
+## Host Integration & Theming
+
+- Registered as WebexPlugin child `cc`; the host supplies credentials, configuration, request routing, logger, internal plugins, and lifecycle. The package renders no UI or theme.
+
+## Cross-Repo Dependency Graph
+
+- **Internal:** sibling `@webex/*` workspace packages supply host, calling, telemetry, authorization, logging, and mercury capabilities.
+- **External services:** WCC REST/WebSocket/RTD and Webex metrics backends.
+- **External read-only:** GitHub/PR history may support rationale; code/tests remain the behavioral referee.
+
+## Security Architecture
+
+The host Webex SDK establishes identity and injects authenticated service routing. Trust boundaries occur at exported SDK input, REST request construction, WebSocket parsing/event mapping, log upload, and metrics submission. Transport security is provided by host-resolved HTTPS/WSS services; durable encryption is remote-service owned.
+
+---
+→ Per-module design: `SPEC_INDEX.md`.
+
+## Architecture Reference Links
+
+| Reference | Location | When to read |
+|---|---|---|
+| Architecture decisions | `adr/` | Durable design choices and supersession |
+| Repo patterns | `patterns/` | Existing TypeScript, event, and testing conventions |
+| Enforceable rules | `RULES.md` | Constraints for every change |
+
+## WS6 References
+
+| WS6 artifact | Relevance to this repo | Link |
+|---|---|---|
+| None routed during onboarding | No separate WS6 artifact was provided. | N/A |

package/ai-docs/CONTRACTS.md

@@ -0,0 +1,46 @@
+# Contracts Catalog — @webex/contact-center
+
+> Start here → root [`AGENTS.md`](../AGENTS.md) · router [`SPEC_INDEX.md`](SPEC_INDEX.md) · system [`ARCHITECTURE.md`](ARCHITECTURE.md). Machine source: `.sdd/manifest.json`.
+
+### Exported API & Types
+| Contract ID | Owner module/package | Symbol | Signature / shape | Stability / deprecation | Schema / detail link | Defined at |
+|---|---|---|---|---|---|---|
+| `contact-center.plugin` | Contact Center | `ContactCenter` / default plugin | WebexPlugin implementing `IContactCenter` | semver public | `ai-docs/contact-center-spec.md` | `src/index.ts` |
+| `contact-center.routing-agent` | Agent/Core | `routingAgent` | `(routing: AqmReqs) => {stationLogin, logout, stateChange, buddyAgents, reload}` | semver public export; returned methods follow backend contracts | `src/services/agent/ai-docs/agent-spec.md` | `src/index.ts`, `src/services/agent/index.ts` |
+| `contact-center.task` | Task | `Task`, `ITask`, task payload/control types | task instance and compatibility interface | semver public | `src/services/task/ai-docs/task-spec.md` | `src/index.ts` |
+| `contact-center.events` | Agent/Task/Config | `AGENT_EVENTS`, `TASK_EVENTS`, `CC_AGENT_EVENTS`, `CC_TASK_EVENTS`, `CC_EVENTS` | typed string event contracts | additive; removals or semantic changes are breaking | owning module specs | `src/index.ts` |
+| `contact-center.data` | Services/Utils | `AddressBook`, `ApiAIAssistant`, SDK data response/search types | SDK data and AI-assistant access | semver public | Services/Utils specs | `src/index.ts` |
+| `contact-center.user-preference` | Services/Config | `UserPreference`, `cc.userPreference`, `UserPreferenceData`, request/response types | `getUserPreference(params?)`, `createUserPreference(data)`, `updateUserPreference(userId, data)`, `deleteUserPreference(userId)` | semver public | `src/services/ai-docs/services-spec.md` | `src/index.ts`, `src/cc.ts`, `src/services/UserPreference.ts`, `src/services/config/types.ts` |
+| `contact-center.preview-campaign` | Contact Center/Task | `acceptPreviewContact`, `skipPreviewContact`, `removePreviewContact` | `(payload: PreviewContactPayload) => Promise<TaskResponse>` | semver public | `ai-docs/contact-center-spec.md`, `src/services/task/ai-docs/task-spec.md` | `src/cc.ts`, `src/services/task/dialer.ts`, `src/services/task/types.ts` |
+| `contact-center.state-controls` | Task state machine | `getDefaultUIControls`, task state/control types | function is exported directly from `uiControlsComputer.ts` by package root | semver public | `src/services/task/state-machine/ai-docs/task-state-machine-spec.md` | `src/index.ts`, `src/services/task/state-machine/uiControlsComputer.ts` |
+
+### Events
+
+| Contract ID | Owner module | Event / topic | Direction | Payload schema link | Delivery guarantees | Compatibility / deprecation | Defined at |
+|---|---|---|---|---|---|---|---|
+| `agent.events` | Agent | `agent:*` | publish to application | agent spec/types | realtime; backend ordering/correlation | additive constants | `src/services/agent/types.ts` |
+| `task.events` | Task | `task:*` | publish to application/task | task spec/types | event-driven; state guarded | additive constants | `src/services/task/types.ts` |
+| `cc.events` | Config/Core | backend CC_EVENTS | consume/map | config/core specs | remote WebSocket delivery; AQM correlation where configured | backend contract | `src/services/config/types.ts` |
+| `rtd.events` | Task | realtime transcription/suggestion | consume then publish per task | task spec | websocket best-effort according to remote service | additive payloads | `src/services/task/TaskManager.ts` |
+
+## Requires — what this repo depends on
+
+| Dependency | What is consumed | Schema / detail link | Availability assumption | Fallback on failure | Version floor |
+|---|---|---|---|---|---|
+| `@webex/webex-core` | plugin host, request/service routing | package declarations | required | fail operation | workspace version |
+| WCC REST/WebSocket | agent/task/config/realtime contracts | module specs and source constants | required for runtime operations | structured error, reconnect, or timeout | remote compatible contract |
+| `@webex/calling` | browser line/call lifecycle | Services/Task specs | required for BROWSER login | surface calling failure | workspace version |
+| internal metrics/mercury/support/auth/logger | telemetry, realtime, support, identity, logging | package declarations | host-dependent | module-specific nonblocking/error path | workspace version |
+
+## Compatibility & Deprecation Policy
+
+- **Breaking-change rule:** no removal, rename, payload reinterpretation, or semantic break without major-version migration and consumer notes.
+- **Deprecation:** mark symbols/types in source/JSDoc, retain through an announced transition, and update changelog/spec/catalog together.
+
+## Detailed Interface Docs
+
+- No OpenAPI/AsyncAPI/proto schema was found in scope; exact SDK and event contracts remain in TypeScript declarations and owning module specs.
+
+## Maintenance
+
+- Update this catalog, the owning module spec, TypeScript declarations, and manifest in the same change as a contract.

package/ai-docs/GETTING_STARTED.md

@@ -0,0 +1,168 @@
+# Getting Started — @webex/contact-center
+
+> Start here → root [`AGENTS.md`](../AGENTS.md) · router [`SPEC_INDEX.md`](SPEC_INDEX.md) · system [`ARCHITECTURE.md`](ARCHITECTURE.md).
+
+## Prerequisites
+- Node.js 22.14 for workspace development; the published package engine floor remains Node >=20.x. Use Yarn 3.4.1 from the workspace.
+- Access to the workspace's npm registries and Webex backend environments is required for integration use.
+
+The `@webex/contact-center` package is a Webex SDK plugin that provides a TypeScript/JavaScript API for building Contact Center agent applications. It enables:
+
+- **Agent Session Management**: Register, login, logout, state changes
+
+- **Task Handling**: Inbound/outbound calls, chat, transfers, conferences
+
+- **Real-time Events**: WebSocket-based notifications for agent and task events
+
+- **Browser-based Calling**: WebRTC integration for browser softphone
+
+- **Metrics & Diagnostics**: Built-in telemetry and log upload
+
+| Technology | Purpose |
+|---|---|
+| **TypeScript** | Primary language with strict mode |
+
+| Technology | Purpose |
+|---|---|
+| **WebexPlugin** | Base class from `@webex/webex-core` |
+
+| Technology | Purpose |
+|---|---|
+| **EventEmitter** | Event handling for real-time updates |
+
+| Technology | Purpose |
+|---|---|
+| **WebSocket** | Real-time communication with Contact Center |
+
+| Technology | Purpose |
+|---|---|
+| **WebRTC** | Browser-based calling (via WebCalling) |
+
+| Technology | Purpose |
+|---|---|
+| **Jest** | Unit testing framework |
+
+## Clone & Install
+```bash
+git clone https://github.com/webex/webex-js-sdk.git
+cd webex-js-sdk
+yarn install
+```
+
+## Build / Run / Test
+| Task | Command |
+|---|---|
+| Build | `yarn workspace @webex/contact-center build:src` |
+| Run locally | Consume through a Webex SDK host/application; this package has no standalone server. |
+| Test | `yarn workspace @webex/contact-center test:unit` |
+| Lint / format | `yarn workspace @webex/contact-center test:style` |
+
+```bash
+yarn workspace @webex/contact-center build:src
+
+yarn workspace @webex/contact-center test:unit
+
+yarn workspace @webex/contact-center test:unit -- test/unit/spec/cc.ts
+
+yarn workspace @webex/contact-center test:style
+```
+
+## First-Run Verification
+- Run the unit suite and confirm Jest enforces the package's 85% global thresholds from `jest.config.js`.
+
+> AI-focused documentation for the `@webex/contact-center` package to enable LLM agents to effectively create, modify, and fix SDK code.
+
+Each service folder contains its own `ai-docs/` with:
+
+- `AGENTS.md` - Usage examples, API reference, quick start
+
+- `ARCHITECTURE.md` - Technical details, sequence diagrams, data flow
+
+| Service | AGENTS.md | ARCHITECTURE.md |
+|---|---|---|
+| Agent | [`src/services/agent/ai-docs/agent-spec.md`](../src/services/agent/ai-docs/agent-spec.md) | [`src/services/agent/ai-docs/agent-spec.md`](../src/services/agent/ai-docs/agent-spec.md) |
+
+| Service | AGENTS.md | ARCHITECTURE.md |
+|---|---|---|
+| Task | [`src/services/task/ai-docs/task-spec.md`](../src/services/task/ai-docs/task-spec.md) | [`src/services/task/ai-docs/task-spec.md`](../src/services/task/ai-docs/task-spec.md) |
+
+| Service | AGENTS.md | ARCHITECTURE.md |
+|---|---|---|
+| Config | [`src/services/config/ai-docs/config-spec.md`](../src/services/config/ai-docs/config-spec.md) | [`src/services/config/ai-docs/config-spec.md`](../src/services/config/ai-docs/config-spec.md) |
+
+| Service | AGENTS.md | ARCHITECTURE.md |
+|---|---|---|
+| Core | [`src/services/core/ai-docs/core-spec.md`](../src/services/core/ai-docs/core-spec.md) | [`src/services/core/ai-docs/core-spec.md`](../src/services/core/ai-docs/core-spec.md) |
+
+## Configuration & Secrets
+- Runtime credentials and service routing come from the host Webex SDK and its environment configuration. Never hardcode or log tokens.
+
+## Dev Environment
+- The package builds inside the Yarn workspace and consumes sibling `@webex/*` packages through workspace dependencies.
+
+```text
+packages/@webex/contact-center/
+├── AGENTS.md                  # Main orchestrator (start here — at package root)
+└── ai-docs/
+    ├── README.md              # This file
+    ├── RULES.md               # Coding standards
+    ├── patterns/              # Pattern documentation
+    │   ├── typescript-patterns.md
+    │   ├── testing-patterns.md
+    │   └── event-driven-patterns.md
+    └── templates/             # Code generation templates
+        ├── README.md
+        ├── new-service/       # Creating new services
+        ├── new-method/        # Adding methods
+        ├── existing-service/  # Bug fixes, features
+        └── documentation/     # Doc generation
+```
+
+```text
+ContactCenter (cc.ts)
+└── Services (singleton)
+    ├── agent/      → Agent operations (login, logout, state)
+    ├── task/       → Task operations (hold, transfer, wrapup)
+    │   └── TaskManager → Task lifecycle
+    ├── config/     → Configuration fetching
+    ├── core/       → WebSocket, HTTP, utilities
+    ├── AddressBook → Address book entries
+    ├── EntryPoint  → Entry points
+    └── Queue       → Queues
+```
+
+## Where to Go Next
+- Agent entry: `../AGENTS.md` · System shape: `ARCHITECTURE.md` · Routing: `SPEC_INDEX.md`
+- Conventions: `patterns/`, `RULES.md`, and the manifest-routed module specification for the target capability.
+
+| Document | Purpose |
+|---|---|
+| [AGENTS.md](../AGENTS.md) | **Start here** - Main AI agent orchestrator (at package root) |
+
+| Document | Purpose |
+|---|---|
+| [RULES.md](RULES.md) | Coding standards and conventions |
+
+| Document | Purpose |
+|---|---|
+| [patterns/](patterns/) | Pattern documentation |
+
+| Document | Purpose |
+|---|---|
+| [templates/](templates/) | Code generation templates |
+
+Start with the root [`AGENTS.md`](../AGENTS.md) for critical repository rules and the developer workflow, then use [`SPEC_INDEX.md`](SPEC_INDEX.md) to classify the task by owning module and open its canonical `*-spec.md`.
+
+When adding new features:
+
+1. Update the relevant service's docs (use the table above to find the right file):
+
+- Service `AGENTS.md` — if usage/API surface changed
+
+- Service `ARCHITECTURE.md` — if data flow or architecture changed
+
+2. Add new patterns to [`patterns/`](patterns/) if introducing new patterns
+
+3. Update [`templates/`](templates/) if the workflow changes
+
+4. Update the root [`AGENTS.md`](../AGENTS.md) if task routing or critical rules changed

package/ai-docs/GLOSSARY.md

@@ -0,0 +1,43 @@
+# Glossary — @webex/contact-center
+
+> Start here → root [`AGENTS.md`](../AGENTS.md) · router [`SPEC_INDEX.md`](SPEC_INDEX.md) · system [`ARCHITECTURE.md`](ARCHITECTURE.md).
+
+## Domain Terms
+
+| Term | Definition (one or two sentences) | Authoritative location (file/type) | Notes / synonyms to avoid |
+|---|---|---|---|
+| ContactCenter | Host-embedded Webex plugin exposing the package API. | `src/cc.ts` | Registered as `cc`. |
+| Agent Profile | Aggregated remote configuration used during an agent session. | `src/services/config/types.ts` | Do not call it durable local state. |
+| Task | Client representation of a contact-center interaction and its operations. | `src/services/task/Task.ts` | Backed by remote interaction data. |
+| AQM request | HTTP initiation whose success/failure may be delivered by correlated WebSocket notification. | `src/services/core/aqm-reqs.ts` | Not request-over-WebSocket. |
+| TaskEvent | Typed internal state-machine event mapped from API calls or backend events. | `src/services/task/state-machine/constants.ts` | Distinct from raw CC_EVENTS. |
+| PageCache | Five-minute in-memory cache for simple paginated data-service requests. | `src/utils/PageCache.ts` | Parameterized searches bypass it. |
+
+## Abbreviations & Acronyms
+
+| Abbreviation | Expansion | Meaning in this repo |
+|---|---|---|
+| WCC | Webex Contact Center | Remote Contact Center service family. |
+| AQM | Agent Queue Manager | Backend operation/correlation pattern. |
+| RTD | Realtime data/transcription | Secondary realtime WebSocket stream. |
+| RONA | Ring On No Answer | Offered-task failure state/event. |
+| ANI | Automatic Number Identification | Outbound caller-id selection data. |
+
+## Context-Specific Meanings
+
+| Term | Context / module | Meaning here |
+|---|---|---|
+| Event | Config/Core | Raw backend WebSocket event. |
+| Event | Task state machine | Typed TaskEvent after mapping. |
+| State | Agent | Backend agent availability/substatus. |
+| State | Task | XState task lifecycle state. |
+
+## Deprecated / Renamed Terms
+
+| Old term | Current term | Why renamed | Still appears in |
+|---|---|---|---|
+| plugin-cc | contact-center | Package rename recorded in history. | Older history and integrations. |
+
+## Maintenance
+
+- Add new entities, events, states, or renamed concepts here in the same change.

package/ai-docs/README.md

@@ -0,0 +1,138 @@
+# Contact Center SDK - AI Documentation
+
+> AI-focused documentation for the `@webex/contact-center` package to enable LLM agents to effectively create, modify, and fix SDK code.
+
+---
+
+## Package Overview
+
+The `@webex/contact-center` package is a Webex SDK plugin that provides a TypeScript/JavaScript API for building Contact Center agent applications. It enables:
+
+- **Agent Session Management**: Register, login, logout, state changes
+- **Task Handling**: Inbound/outbound calls, chat, transfers, conferences
+- **Real-time Events**: WebSocket-based notifications for agent and task events
+- **Browser-based Calling**: WebRTC integration for browser softphone
+- **Metrics & Diagnostics**: Built-in telemetry and log upload
+
+---
+
+## Technologies
+
+| Technology | Purpose |
+|------------|---------|
+| **TypeScript** | Primary language with strict mode |
+| **WebexPlugin** | Base class from `@webex/webex-core` |
+| **EventEmitter** | Event handling for real-time updates |
+| **WebSocket** | Real-time communication with Contact Center |
+| **WebRTC** | Browser-based calling (via WebCalling) |
+| **Jest** | Unit testing framework |
+
+---
+
+## Quick Links
+
+| Document | Purpose |
+|----------|---------|
+| [AGENTS.md](../AGENTS.md) | **Start here** - Main AI agent orchestrator (at package root) |
+| [SPEC_INDEX.md](SPEC_INDEX.md) | Route work to the owning canonical module specification |
+| [RULES.md](RULES.md) | Coding standards and conventions |
+| [patterns/](patterns/) | Pattern documentation |
+| [templates/](templates/) | Code generation templates |
+
+---
+
+## For AI Agents
+
+### Starting a Task
+
+Start with the root [`AGENTS.md`](../AGENTS.md) for critical repository rules and the developer workflow, then use [`SPEC_INDEX.md`](SPEC_INDEX.md) to classify the task by owning module and open its canonical `*-spec.md`.
+
+---
+
+## Directory Structure
+
+```
+packages/@webex/contact-center/
+├── AGENTS.md                  # Main orchestrator (start here — at package root)
+└── ai-docs/
+    ├── README.md              # This file
+    ├── SPEC_INDEX.md          # Canonical module router
+    ├── contact-center-spec.md # Canonical public plugin specification
+    ├── CONTRACTS.md           # Public contract catalog
+    ├── adr/                   # Durable architecture decisions
+    ├── RULES.md               # Coding standards
+    ├── patterns/              # Pattern documentation
+    │   ├── typescript-patterns.md
+    │   ├── testing-patterns.md
+    │   └── event-driven-patterns.md
+    └── templates/             # Code generation templates
+        ├── README.md
+        ├── new-service/       # Creating new services
+        ├── new-method/        # Adding methods
+        ├── existing-service/  # Bug fixes, features
+        └── documentation/     # Doc generation
+```
+
+---
+
+## Package Commands
+
+```bash
+# Build
+yarn workspace @webex/contact-center build:src
+
+# Test unit tests
+yarn workspace @webex/contact-center test:unit
+
+# Test specific file
+yarn workspace @webex/contact-center test:unit -- <path_of_test_file>
+
+# Lint
+yarn workspace @webex/contact-center test:style
+```
+
+---
+
+## Service Architecture
+
+```
+ContactCenter (cc.ts)
+└── Services (singleton)
+    ├── agent/      → Agent operations (login, logout, state)
+    ├── task/       → Task operations (hold, transfer, wrapup)
+    │   └── TaskManager → Task lifecycle
+    ├── config/     → Configuration fetching
+    ├── core/       → WebSocket, HTTP, utilities
+    ├── AddressBook → Address book entries
+    ├── EntryPoint  → Entry points
+    └── Queue       → Queues
+```
+
+---
+
+## Canonical Module Specifications
+
+Use [`SPEC_INDEX.md`](SPEC_INDEX.md) to select the owning module. Each manifest-routed module has one canonical `*-spec.md`; retained module-level `AGENTS.md` and `ARCHITECTURE.md` files are legacy/reference-only migration sources, as recorded in [`ADR-0001`](adr/0001-spec-source-policy.md).
+
+| Module | Canonical specification |
+|---|---|
+| Contact Center public plugin | [`contact-center-spec.md`](contact-center-spec.md) |
+| Metrics | [`metrics-spec.md`](../src/metrics/ai-docs/metrics-spec.md) |
+| Services composition | [`services-spec.md`](../src/services/ai-docs/services-spec.md) |
+| Agent | [`agent-spec.md`](../src/services/agent/ai-docs/agent-spec.md) |
+| Config | [`config-spec.md`](../src/services/config/ai-docs/config-spec.md) |
+| Core | [`core-spec.md`](../src/services/core/ai-docs/core-spec.md) |
+| Task | [`task-spec.md`](../src/services/task/ai-docs/task-spec.md) |
+| Task state machine | [`task-state-machine-spec.md`](../src/services/task/state-machine/ai-docs/task-state-machine-spec.md) |
+| Utils | [`utils-spec.md`](../src/utils/ai-docs/utils-spec.md) |
+
+---
+
+## Contributing to AI Docs
+
+When adding new features:
+1. Use [`SPEC_INDEX.md`](SPEC_INDEX.md) to select the owning canonical module specification.
+2. Update that `*-spec.md` with the behavior, source evidence, test evidence, and known gaps.
+3. For exported API, event, or type changes, also update [`CONTRACTS.md`](CONTRACTS.md), the Contact Center specification, and `.sdd/manifest.json` when its routing, coverage, or validation evidence changes.
+4. Add or update [`patterns/`](patterns/) and [`templates/`](templates/) only when their reusable guidance changes.
+5. Update the root [`AGENTS.md`](../AGENTS.md) when task routing or critical rules change. Do not update retained service `AGENTS.md` or `ARCHITECTURE.md` as an independent source of truth.