Support & Operations Troubleshooting Runbook

This guide equips customer support agents, system operators, and onboarding engineers with clear diagnostic steps and resolution actions for recurring issues.

1. Fast Diagnostic Triage Matrix

User Symptom	Likely Root Cause	Immediate Verification Step	Resolution Procedure
“Brak uprawnień” / Missing Menu Options	Incorrect Role or Tenant Context	Check active workspace in top app bar.	Switch to correct cooperative workspace in `TenantSessionProvider` or grant role in Admin panel.
Jarvis “Błąd nagrywania” / Microphone Failure	OS-level permission denied or HTTP origin	Check browser URL or mobile app settings.	Ensure URL is HTTPS. In mobile OS settings, enable microphone access for PLANOVI.
Inverter / Battery Shows Offline	Modbus gateway timeout or stale telemetry	Check “Ostatnia aktualizacja” timestamp on device card.	Restart IoT gateway or trigger `refresh-live-state` edge function.
Voting Button Inactive in Governance	KYC declaration not approved or quorum closed	Check member status in `TeamDeclarationsScreen`.	Admin must approve the pending declaration before voting eligibility unlocks.
Unable to open DOCX / PDF contract	Storage CORS or missing file mime type	Inspect browser developer tools network tab.	Verify Supabase Storage bucket `documents` has public read policy enabled.

2. Common Support Scenarios

Scenario A: Member Switched Cooperatives and Sees Empty Dashboard

Why it happens: Energy cooperative data is segregated strictly by company_id. If a user belongs to multiple organizations (e.g. Spółdzielnia Słoneczna Dolina and Firma XYZ Sp. z o.o.), viewing the wrong workspace will show blank data.
Support Action: Instruct the user to click their profile picture in the top-right corner, select Przełącz przestrzeń roboczą (Switch Workspace), and choose the cooperative marked with the Energy icon (cooperative).

Scenario B: Jarvis Audio Fails on Mobile Safari / Chrome Web

Why it happens: Modern browsers block auto-playing audio without prior user gesture, and prohibit microphone access on plain HTTP connections.
Support Action:
1. Confirm the user is accessing the app via https://....
2. Explain that the user must tap the screen at least once before speech audio output can automatically play.

Scenario C: Tauron Telemetry CSV Import Failed

Why it happens: Energy distribution CSV headers vary between Tauron Dystrybucja regional branches or export dates.
Support Action:
1. Have the user forward the exported CSV file.
2. Inspect the timestamp column format (expected: YYYY-MM-DD HH:mm:ss or Polish date notation DD.MM.YYYY).
3. Verify the process-tauron-csv Edge function logs in Supabase Dashboard.