Troubleshooting

The app now prefers readiness output over hard crashes, so most operational issues are surfaced directly in the dashboard or platform health page.

• cPanel shows a blank page or 500 immediately after upload: confirm Operix-public.zip was extracted inside public_html/Operix and Operix-root.zip was extracted to /home/USERNAME/Operix.
• Public index cannot find the app: confirm public_html/Operix/index.php points to ../../Operix and the root folder name is exactly Operix.
• Installer does not start: confirm .env was not uploaded from localhost, storage/app/installed is absent, and /Operix/storage plus /Operix/bootstrap/cache are writable.
• Documentation is missing from cPanel root: confirm Operix-root.zip contains Operix/docs/Operix; docs are intentionally not included in public_html.
• Installer finish is blocked: check clinic_name, clinic_phone, clinic_email, clinic_address, mail defaults, distinct admin or doctor or receptionist accounts, the plan catalog, and first-clinic bootstrap state in the readiness console.
• Public plans, signup, or commercial pages show degraded readiness instead of data: central schema is behind code, so run migrations first and use platform operations for diagnosis before retrying launch.
• Public signup or SSO stalls before launch: verify identity.self_serve.enabled, provider credentials in config/identity.php, and whether owner email verification is required before launch.
• Missing tenant database file, schema, or migrations: clinic entry attempts tenant bootstrap repair first, then platform health shows the remaining readiness reason if the clinic is still degraded.
• Existing tables with an empty migrations table: run Operix:repair-migration-state in dry-run mode first, then rerun with --write if the baseline is correct.
• Pharmacy or billing tables absent: tenant dashboard swaps those widgets for readiness cards.
• Communications templates or AI analytics tables absent: tenant repair recreates the runtime tables and the dashboard keeps loading with readiness output.
• Queue or scheduler not running: daily briefs, digests, and alerts stop advancing but the tenant shell still loads.
• AI provider credentials missing: AI settings shows provider health failure and AI actions stay disabled.
• SSO setup looks wrong: confirm enabled state, client credentials, redirect URI alignment, and domain policy from the platform SSO operator summary.
• Twilio callbacks failing or SMS or WhatsApp stuck pending: confirm tenant channel settings, provider credentials, callback route reachability, signature handling, duplicate suppression, and patient opt-out state from the Twilio operator summary.
• Suspended clinics or memberships: clinic switching is blocked until the platform admin reactivates access.
• Demo clinic is no longer buyer-ready: reset it through Demo Concierge or Operix:reset-demo and refresh evidence and smoke status.

The operator workflow is now explicit. Audit first, then repair, then refresh snapshots and rerun smoke coverage.

• php artisan Operix:audit-tenants
• php artisan Operix:repair-tenant {tenant} --write
• php artisan Operix:repair-migration-state central --write
• php artisan Operix:seed-demo --profile=sales
• php artisan Operix:refresh-platform-health
• php artisan Operix:refresh-commercial-health
• php artisan Operix:reset-demo --clinic={tenant}
• npm run release:gate

Keep demo repair separate from production panic. The goal is to re-establish a deterministic story quickly, then prove it with evidence and smoke status.

• Use healthy demo when you need a polished buyer story and degraded demo when you need to prove fail-soft readiness behavior.
• Refresh platform health and commercial snapshots before capturing evidence or handing a clinic to sales.
• If evidence or smoke status is stale, rerun capture and smoke helpers before trusting screenshots or demo claims.