RUNBOOK

• Agent-skill standard entrypoint is SKILL.md.
• This runbook is an operational convention (recommended), not a required skill file.
• SKILL.md is also a navigation convention for larger skill docs.

1) Confirm Two-Role Model

• Customer role (role_type=1) starts session.
• Agent role (role_type=2) joins session.

If your demo only has one generic role, expect broken join behavior.

2) Confirm PIN Source of Truth

• Use customer SDK event pincode_updated as the only user-facing PIN.
• Agent must join with that same PIN.
• Do not show provisional/debug PIN values from backend records.

Common symptom if wrong: Pincode is not found / error 30308.

3) Confirm JWT Claims

• Sign JWT on backend only.
• Include required claim names exactly (for example user_id, not custom aliases).
• Use SDK Key for SDK token context; keep SDK Secret server-side.

If claim names are wrong, token is rejected before session logic.

4) Confirm Session Order

Recommended sequence:

1. Customer gets customer JWT and starts session.
2. PIN is generated on customer side (pincode_updated).
3. Agent gets agent JWT and joins with that PIN.

Starting agent flow before customer session is active often causes join failures.

5) Confirm Distribution Pattern

• CDN path: customer SDK + Zoom-hosted agent desk iframe.
• npm path: custom integration (BYOP mode required for custom PIN control).

If using npm agent integration without BYOP expectations, flow mismatches happen.

6) Confirm Browser and Security Constraints

• HTTPS required (except loopback/local dev).
• CSP/CORS must allow Zoom domains.
• Third-party cookie/privacy settings can affect reconnect behavior.

Do not treat extension/adblock warnings as root cause until API/session checks fail.

7) Quick Checks (Backend + UI)

• Backend config endpoint returns expected credential flags.
• Customer page shows a single Support PIN from SDK event.
• Agent page join uses same Support PIN and returns actionable response (not generic 404).

Copy/Paste Validation Commands

Expected: customer/agent pages load and config endpoint returns valid JSON flags.

8) Fast Decision Tree

• Invalid token -> check JWT claim names and signing secret.
• Agent cannot find PIN -> wrong PIN source or wrong session order.
• Session drops on refresh -> check reconnection window and browser privacy/cookies.
• Works locally, fails prod -> check HTTPS, CSP/CORS, reverse proxy pathing.