> ## Documentation Index > Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt > Use this file to discover all available pages before exploring further. # Telehealth Documentation & Compliance — Admin Guide > Admin: module settings, rollout stages, compliance dashboard, overrides, cron playbook, consent-language lineage. **Required permission:** `cl.telehealth_compliance.audit` for the dashboard; `cl.admin` for overrides *** ## Module settings Navigate to **Clinical → Settings → Telehealth Documentation** (requires `cl.admin`). All settings live on `cl_module_settings` and are tenant-scoped. | Setting | Type | Default | Behavior | | --------------------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `telehealth_documentation_enabled` | boolean | `false` | Master switch. When `false`, CL-24 hooks short-circuit, the badge / sheet / pages are not mounted, and PM-13 sees no CL-24 surface. Use this to keep CL-24 off in orgs that aren't ready for the compliance layer. | | `telehealth_block_session_without_consent` | boolean | `true` | When `true`, the start-session orchestrator returns `ConsentRequiredError` if `cl_telehealth_consent_is_valid` returns false for the required `consent_type`. When `false`, the UI warns but does not block. | | `telehealth_block_session_without_safety_checklist` | boolean | `true` | When `true`, the start-session orchestrator returns `SafetyChecklistRequiredError` until `safety_checklist_completed_at` is stamped. When `false`, the UI warns but does not block. | | `telehealth_consent_validity_days` | integer | `365` | Default validity window for new consents. The `expires_at` column is `consented_at + telehealth_consent_validity_days`. Common alternatives: `730` (CCBHC 2-year cycles) or `90` for pilot rollouts. | A fourth flag is conceptually "audio-only consent required separately" — this is enforced **per jurisdiction** via the consent-language version, not a separate boolean. See [Consent language version lineage](#consent-language-version-lineage) below. ### Settings change audit Every change to these settings is tracked via the standard `updated_at` + `updated_by` capture (the `update_updated_at_column` trigger keeps `updated_at` current; the application layer stamps `updated_by`). Audit-row writes to `pf_audit_logs` are produced by the platform's settings-edit pipeline, not by this trigger. No CL-24-specific audit table. *** ## Feature-flag rollout — stages 0 through 4 CL-24 ships with a five-stage rollout. Each stage is gated by the master flag plus the two block flags above. The intent is to give clinicians time to develop the muscle memory before hard-block goes on. | Stage | `telehealth_documentation_enabled` | Consent block | Safety block | Use when | | ------------------------------------ | ---------------------------------- | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **0 — Dormant** | `false` | n/a | n/a | Pre-rollout. CL-24 surface is invisible; PM-13 unchanged. | | **1 — Surface-only** | `true` | `false` | `false` | Soft launch. Badge, sheet, pages render. Clinicians can capture consents and run checklists but nothing blocks. Use for clinician training. **Default for NorthSight starting Stage 1.** | | **2 — Consent warns, safety warns** | `true` | `false` | `false` | Same as Stage 1; included for explicit gating language. | | **3 — Consent blocks, safety warns** | `true` | `true` | `false` | After ≥ 4 weeks of Stage 1/2 with consent-capture rate ≥ 85% on the dashboard. Sessions without valid consent will fail; safety checklist still warn-only. | | **4 — Full compliance** | `true` | `true` | `true` | After Stage 3 has been clean for ≥ 4 weeks. This is the steady-state for AHCCCS CBHSG (Oct 2025), CCBHC v2, and Joint Commission CAMBHC alignment. | > Move only one block flag per cycle. Never go from Stage 1 directly to Stage 4 — the safety-checklist habit takes longer to build than consent capture, and a hard block on day one will cause clinicians to bypass via the chart-of-record fallback. Stage progression is logged in `specs/cl/IMPLEMENTATION_LOG.md` per org. *** ## Compliance dashboard interpretation Navigate to **Clinical → Telehealth → Compliance** (`/cl/telehealth/compliance`, requires `cl.telehealth_compliance.audit`). The dashboard surfaces four primary metrics for the selected period (last 7, 30, or 90 days, default 30): | Metric | Formula | Healthy range | Action when red | | ------------------------------------ | -------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Consent capture rate** | `valid_consents_at_session_start / total_sessions` | ≥ 0.95 | Look at the per-clinician breakdown; schedule a refresher on the consent dialog flow. | | **Safety checklist completion rate** | `sessions_with_safety_completed / total_sessions` | ≥ 0.90 (Stage 3) → 1.00 (Stage 4) | If below 0.90 for ≥ 2 weeks, do not advance to Stage 4. Investigate whether the warn-mode UX is being routinely dismissed. | | **Audio-only ratio** | `audio_only_sessions / total_sessions` | \< 0.20 typically | High ratios may indicate connectivity issues regionally — cross-check with the connectivity-issue panel. | | **Jurisdiction mismatch rate** | `mismatched_state_sessions / total_sessions` | \< 0.05 | Often signals a clinician's profile state is stale. Audit `pf_profiles.state` for telehealth providers. | Each metric drills down into the contributing rows. Drill-downs are RLS-filtered to the current org. > The dashboard uses small-cell suppression (n \< 5 displays as `<5`) for any per-clinician slice when the org has fewer than 5 telehealth providers, to honor 45 CFR 164.514(b) safe-harbor on indirect identification. *** ## Admin override for `revoked_at` immutability The trigger `cl_enforce_consent_revocation_immutability` rejects any UPDATE that changes `revoked_at` once it is set — **except** when `pf_is_org_admin(organization_id, auth.uid())` returns true. ### Why it exists Revocation is a clinical-legal event. Once a patient revokes consent, the row is part of the audit record (Joint Commission CAMBHC, AHCCCS CBHSG, and 42 CFR 164 expectations for behavioral-health record retention). Letting any clinician clear `revoked_at` would create a trivial path to scrub the record. But mistakes happen. A clinician may click the wrong patient, or a portal API may misfire. The override is the supervised escape valve. ### How to invoke 1. Open **Clinical → Telehealth → Consents → All consents** (admin-only filter). 2. Find the row in question. Inspect the revocation reason. 3. Click **Reverse revocation** — visible only when you hold `pf_is_org_admin` and the row's `revoked_at` is set. 4. Enter a justification (free-text, required, ≥ 30 chars). 5. Submit. The system: * UPDATEs `revoked_at = NULL`, `revoked_reason = NULL` (trigger allows this because you're an admin). * Writes an audit row to `pf_audit_logs` with the justification. * Emits `cl_telehealth_consent_captured` is **not** re-emitted (the row is the same, not a new one); use the override sparingly and document downstream notifications manually. > Every override is reviewed by the compliance officer monthly. If the rate exceeds 1 per 1000 active consents, treat as an incident. *** ## Cron failure playbook CL-24 runs one cron job: * **`cl-telehealth-consent-expiry-scan`** — nightly at 03:00 UTC. Idempotent within a 24h window via `cl_cron_run_log`. Emits `cl_telehealth_consent_expiring` for any consent with `revoked_at IS NULL` and `expires_at` ≤ `now() + interval '30 days'`. ### Detect a failure * **`cl_cron_run_log`** has no row for the current 24h window past 04:00 UTC. * The `cl_telehealth_consent_expiring` event count drops to zero for ≥ 24 hours when the dashboard shows pending expiries. * `pf_supervisor_alerts` raises `cl_cron_unhealthy` (if Supabase logs are wired through PF-44). ### Recover 1. Inspect `cl_cron_run_log` for the last successful run timestamp and outcome. 2. From the Supabase MCP / dashboard, check the `cl-telehealth-consent-expiry-scan` edge function logs for stack traces. 3. **Manual re-run:** invoke the function with `{ as_of: "", force: true }`. The function is idempotent on `(consent_id, run_window_start)` — re-runs do not double-publish. 4. If the failure was schema-related (e.g., a recent migration changed `cl_telehealth_consents`), open an incident, revert the migration, and replay the cron. 5. Document the incident in `specs/cl/IMPLEMENTATION_LOG.md` and `docs/compliance/REGULATORY_COMPLIANCE_TRACKER.md` (Joint Commission row, interim procedures). ### Prevent repeats * Add a `pg_cron` health check that asserts at least one `cl_cron_run_log.outcome = 'success'` row in the last 25 hours. * The function should already use the platform system actor UUID (`00000000-0000-0000-0000-000000000001`) per the [CL-FW automated-publishers contract](/architecture/integrations/CL-FW-EVENT-AUTOMATION-INTEGRATION). *** ## ARS 13-3005 language template sign-off Arizona is a **two-party consent** state for recordings (ARS 13-3005). When the org's primary jurisdiction is AZ (`pf_organizations.state = 'AZ'`), the `consent_language_version` for telehealth recordings must match the org's approved AZ template. ### Sign-off workflow 1. Compliance officer drafts the template using the canonical reference at `docs/compliance/templates/ars-13-3005-recording-notice.md` (or its successor under PF-96 jurisdiction profiles). 2. Legal / external counsel reviews and approves. 3. Org admin opens **Clinical → Telehealth → Consent language versions** and creates a new version: e.g., `AZ-ARS-13-3005-v3-2026Q3`. 4. Mark the version `active = true`. CL-24 will surface it in the consent dialog as the default for AZ-jurisdiction orgs. 5. Record sign-off in `specs/cl/reviews/CL-24-COMPLIANCE-SIGNOFF.md` with date, signer, and template diff. > Stage 2 cannot advance to Stage 3 until the active AZ template is sign-off-recorded. The compliance dashboard surfaces `consent_language_version` distribution so you can see whether older templates are still in active circulation. For non-AZ jurisdictions, PF-96 (Medicaid State Compliance Configuration) provides the per-state template; CL-24 inherits whichever version PF-96 marks active for the org's primary state. *** ## Consent language version lineage `consent_language_version` is a free-text identifier on every consent row. It is **never** mutated — once a consent is captured against version `AZ-ARS-13-3005-v2-2026Q1`, that row stays at v2 forever, even after v3 is active. ### Why lineage matters A patient revocation in 2027 may need to reference the exact language the patient agreed to in 2026. If versions were overwritten, the audit chain would break — a problem at survey time for Joint Commission CAMBHC and CCBHC v2. ### Recommended naming `{JURISDICTION}-{STATUTE}-{V}-{YYYY}{Q}` — e.g., `AZ-ARS-13-3005-v3-2026Q3`, `US-FED-v1-2026Q1`. ### Operating procedure 1. Maintain a master list under `docs/compliance/templates/` mirroring every version ever used. 2. When you mark a new version active, **do not** delete the prior version's master file — append a `superseded_by` note. 3. Quarterly, run the compliance dashboard filter **Group by consent\_language\_version** to confirm no consents older than 2 versions back are still active. If they are, schedule renewals. 4. The cron `cl-telehealth-consent-expiry-scan` does **not** auto-rotate language versions. Patients renew on the natural `expires_at` cycle and pick up whatever version is active at renewal time. *** ## Troubleshooting | Symptom | Likely cause | Fix | | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `ConsentRequiredError` raised at session start despite a visible badge | `cl_telehealth_consent_is_valid` returned false. Check expiry, revocation, and consent\_type. | Capture a fresh consent of the required type. | | `SafetyChecklistRequiredError` raised at session start | Stage 4 is on; the safety checklist is incomplete. | Open the safety checklist sheet; complete the three required fields. | | Cron published 0 events but consents are clearly expiring | `cl_cron_run_log` has no row → cron didn't run, OR all expiring consents already had a prior 24h-window event. | Run the cron-failure playbook above. | | Connectivity-issue entries do not appear on the dashboard | The dashboard only counts entries within the selected period. Default is 30 days. | Widen the window. | | Jurisdiction-mismatch rate spiked overnight | A clinician's profile state may have been updated incorrectly. | Audit `pf_profiles.state` for the affected user. | | The admin override button is not visible for an admin | `pf_is_org_admin(organization_id, auth.uid())` returned false for the *target* org. | Confirm the admin's role binding for the specific org. | *** ## References * [CL-24 spec](https://github.com/Encore-OS/encoreos/blob/development/specs/cl/specs/CL-24-telehealth-documentation-compliance.md) * [CL-24 user guide](/cl/telehealth-documentation-user-guide) * [CL-24 integration contract](/architecture/integrations/telehealth-documentation-compliance-integration) * [CL-PM Telehealth integration contract](/architecture/integrations/CL-PM-TELEHEALTH) * [Regulatory compliance tracker — Telehealth row](/compliance/REGULATORY_COMPLIANCE_TRACKER) * [ARS 13-3005 reference](https://www.azleg.gov/ars/13/03005.htm) * [AHCCCS CBHSG Oct 2025 telehealth chapter](https://www.azahcccs.gov/Resources/Downloads/CBHSG_Manuals/) (operationally maintained by Compliance)