SupportPilot

SupportPilot is an enterprise AI support workspace with a preserved Lite embeddable chat path. It can run locally from seeded demo data, then switch to Supabase-backed auth, tickets, RAG, approval workflows, audit logs, analytics, and Sentry observability when env vars are configured.

Stack

• Next.js 16 App Router and React 19
• Tailwind CSS v4
• Vercel AI SDK v6 with Google, OpenAI, or Anthropic providers
• Supabase Auth, Postgres, pgvector, Storage-ready knowledge uploads, and RLS
• Workspace settings, DNS-verified widget domains, usage events, and approval policies
• Onboarding checklist, workspace health, model route logs, security events, signed widget sessions, missing-knowledge tasks, and optional Redis-backed public API rate limits
• Launch/Pro billing usage limits, Stripe checkout/webhook lifecycle foundation, entitlements, invoices, and portal handoff
• Provider-aware knowledge embeddings with deterministic fallback, embedding metadata, re-embedding job scaffolding, and background ingestion job scaffolding
• Slack/generic webhook integration foundation with durable outbound events and delivery logs
• Retention deletion request jobs and tamper-evident chained audit evidence exports
• Secure active-workspace switching, verified-domain SAML JIT mapping, TOTP MFA, and recorded access reviews
• Supabase Vault-backed write-only integration credentials with rotation/use audit metadata
• Server-side model orchestration with protected BYOK connections, shared Qwen3 4B allowance controls, R0-R5 route telemetry, circuit breaking, and staged voice-pilot governance
• Optional Resend invitation/escalation email and PostHog product events
• Sentry for optional app error monitoring
• PDF, Markdown, and text knowledge ingestion

Run Locally

npm install
cp .env.local.example .env.local
npm run dev

The app works without provider or Supabase credentials by using deterministic seeded enterprise data and the Lite retriever fallback.

Routes

• / - premium marketing page with dashboard hero, widget proof, pricing, security, FAQ, and demo CTAs
• /embed - iframe chat panel
• /widget-test - script embed test page
• /portal - customer-facing support/chat entry point
• /login - Supabase staff sign-in when enterprise env vars exist
• /admin - enterprise dashboard overview
• /admin/tickets - ticket inbox with status, priority, agent, and risk filters
• /admin/tickets/[ticketId] - ticket detail, conversation, citations, and AI draft side panel
• /admin/knowledge - doc upload, ingestion status, approved source list
• /admin/approvals - high-risk draft approval queue with manager SLA due/overdue metadata
• /admin/analytics - resolution, acceptance, response, escalation, and missing-topic metrics
• /admin/billing - Launch/Pro usage limits, model route cost, invoices, and optional Stripe portal
• /admin/settings - workspace brand, escalation email, widget key, DNS-verified domains, approval policies

API

• POST /api/chat - embeddable/customer chat, with Lite fallback, workspace origin checks, and enterprise AI run/audit logging
• GET /api/widget/config - public widget configuration scoped by workspace key and verified origin
• POST /api/widget/session - optional signed widget session for verified origins when SUPPORTPILOT_WIDGET_SESSION_SECRET is configured
• GET /api/health - secret-safe deployment health snapshot for Supabase, invitation email, Sentry, Redis, workers, and Stripe config
• GET /api/stats - dashboard metrics from the enterprise service layer, optionally scoped by workspace
• GET /api/onboarding/state - workspace launch checklist, health, golden questions, missing knowledge, and retention settings
• GET /api/workspaces and POST /api/workspaces/active - list authenticated memberships and securely select the active workspace (POST /api/workspaces remains a compatibility alias)
• GET|PATCH|POST /api/security/identity - owner/admin SAML domain policy, safe JIT defaults, and access-review records
• POST /api/onboarding/steps/[step]/complete - mark a launch checklist step complete
• POST /api/evals/golden/run - worker-secret scheduled golden-question eval run with persisted pass/fail evidence
• GET /api/security/events - workspace security event feed
• GET|POST /api/security/deletion-requests - manager/admin data deletion request intake with verification and queued jobs
• GET|POST /api/security/retention/jobs - retention cleanup job list and scheduler driven by workspace settings
• POST /api/security/retention/jobs/run - worker-secret batch drain for queued retention/deletion jobs
• POST /api/security/retention/jobs/[jobId]/run - manually or worker-run a queued retention/deletion job
• GET|POST /api/security/audit-exports - tamper-evident audit/security evidence export records
• GET /api/model-routes - AI model route/cost/latency log feed
• GET|PATCH /api/ai/config - owner/admin model provider mode, protected primary connection, budgets, fallback policy, and data residency
• POST /api/ai/providers/test - owner/admin server-side provider health check; credentials never leave the server
• GET /api/ai/usage - workspace AI route, token, latency, fallback, and estimated-cost summary
• POST /api/evals/models/compare - evaluate Qwen3 4B and Gemma 4 E4B against approved golden questions and optionally promote the passing winner
• GET|PATCH /api/voice/config - disabled-by-default ElevenLabs/Speechmatics pilot benchmark configuration
• POST /api/billing/checkout - owner-only Launch/Pro hosted Checkout session creation; demo fallback is local-only and production fails closed when Stripe secret or price IDs are missing
• POST /api/billing/webhook - verified Stripe webhook receiver for checkout, subscription, invoice, entitlement, and dunning state sync; floods are rate limited before body parsing and processing failures are redacted before persistence/response
• GET /api/billing/subscription - owner-only internal billing lifecycle state for the active workspace
• GET|POST /api/billing/reconciliation - owner-readable and scheduler-runnable Stripe readiness report for price catalog, customer, subscription, invoice, entitlement, and checkout drift
• GET|POST /api/billing/portal - create a Stripe customer portal session from tenant customer mapping or legacy env customer; demo fallback is local-only and production fails closed without Stripe/customer config
• GET|POST /api/integrations/accounts - owner/admin integration account and generic webhook endpoint configuration with redacted reads
• GET /api/integrations/events - manager/admin outbound integration event and delivery log feed
• POST /api/integrations/events/[eventId]/deliver - manually or worker-run a queued integration delivery
• POST /api/integrations/events/deliver - worker-secret batch delivery for due queued integration events
• GET|POST /api/knowledge/missing - missing-source task list and creation endpoint
• GET|POST /api/knowledge/reembed - manager/admin/owner re-embedding job endpoint for approved knowledge chunks
• GET /api/knowledge/ingest/jobs - manager/agent ingestion job history for uploads, PDFs, retries, and extraction failures
• POST /api/knowledge/ingest/jobs/[jobId]/run - manually retry or worker-run a queued ingestion job
• POST /api/knowledge/ingest/jobs/run - worker-secret batch drain for due queued ingestion jobs
• POST /api/knowledge/crawl - owner/admin/manager/agent website or sitemap ingestion through a bounded public crawler and the normal ingestion job pipeline
• POST /api/feedback - answer feedback logging bound to the persisted AI run and approved widget origin in production
• POST /api/knowledge/upload - upload or paste .md, .txt, or .pdf; small text runs inline, large/PDF jobs can queue for background extraction
• POST /api/tickets/[ticketId]/draft - create AI draft reply with citations, confidence, rationale, risk flags, and ai_run
• PATCH /api/ai-runs/[aiRunId]/decision - approve, edit, reject, or escalate drafts with audit logs
• PATCH /api/workspaces/[workspaceId]/settings - update workspace identity, brand, welcome copy, and escalation routing
• GET|POST /api/workspaces/[workspaceId]/domains - list or add widget origins with DNS verification instructions
• POST /api/workspaces/[workspaceId]/domains/[domainId]/verify - check TXT/CNAME records and activate a widget origin
• POST /api/workspaces/[workspaceId]/domains/recheck - owner/admin or worker-secret DNS health recheck for verified/pending domains
• POST /api/escalations/email - optional Resend-backed escalation email with audit and usage logging
• POST /api/workspaces/[workspaceId]/invitations - owner/admin invitation creation with hashed tokens, entitlement checks, Resend delivery, and audit logging
• GET /api/integrations/health - owner/admin/manager integration delivery health summary with active channels, queued retries, failures, and success rate

Enterprise Env

SUPPORTPILOT_APP_MODE=production # demo | production
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...
NEXT_PUBLIC_SUPPORTPILOT_OAUTH_PROVIDERS=google,github # optional; enable only providers configured in Supabase Auth
SUPPORTPILOT_PORTAL_WORKSPACE_ID=... # production customer portal workspace, unless resolved from an existing portal identity
SUPPORTPILOT_SUPABASE_REQUEST_TIMEOUT_MS=5000 # bounded server-side Supabase request timeout
SUPPORTPILOT_SAML_VERIFIED_DOMAINS=company.example # hosted Supabase SAML domains that passed deployment verification
SUPPORTPILOT_SAML_REHEARSED_AT=2026-08-13T00:00:00Z # set only after live IdP rehearsal

LLM_PROVIDER=google # google | openai | anthropic
GOOGLE_GENERATIVE_AI_API_KEY=...
GOOGLE_MODEL=gemini-2.5-flash
OPENAI_API_KEY=...
OPENAI_MODEL=gpt-4o-mini
ANTHROPIC_API_KEY=...
ANTHROPIC_MODEL=claude-3-5-haiku-latest

SENTRY_DSN=...
NEXT_PUBLIC_SENTRY_DSN=...
SENTRY_ORG=...
SENTRY_PROJECT=...
SENTRY_AUTH_TOKEN=...

NEXT_PUBLIC_APP_URL=...
SUPPORTPILOT_WIDGET_SESSION_SECRET=...
SUPPORTPILOT_DOMAIN_CNAME_TARGET=verify.supportpilot.ai
SUPPORTPILOT_DOMAIN_RECHECK_SECRET=...
SUPPORTPILOT_DOMAIN_ALERT_WEBHOOK_URL=...
SUPPORTPILOT_DOMAIN_STALE_DAYS=30
MODEL_ROUTER_DEFAULT=light
EMBEDDING_PROVIDER=deterministic # deterministic | local | openai | google
EMBEDDING_MODEL=...
EMBEDDING_VERSION=v1
EMBEDDING_DIMENSIONS=768
SUPPORTPILOT_ALLOW_DETERMINISTIC_EMBEDDINGS=false
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
GOOGLE_EMBEDDING_MODEL=text-embedding-004
LOCAL_EMBEDDING_MODEL=...
LOCAL_MODEL_ENDPOINT=...
LOCAL_MODEL_NAME=...
LOCAL_MODEL_API_KEY=... # optional bearer token for a protected local endpoint
LOCAL_MODEL_TIMEOUT_MS=20000
LOCAL_EMBEDDING_ENDPOINT=...
LOCAL_EMBEDDING_API_KEY=... # optional bearer token for a protected local embedding endpoint
LOCAL_EMBEDDING_TIMEOUT_MS=10000
LOCAL_RERANKER_ENDPOINT=...
LOCAL_RERANKER_API_KEY=... # optional bearer token for a protected local reranker
LOCAL_RERANKER_TIMEOUT_MS=10000
SUPPORTPILOT_OPEN_MODEL_ENDPOINT=... # private vLLM/OpenAI-compatible endpoint, or Ollama in local development
SUPPORTPILOT_OPEN_MODEL_NAME=qwen3:4b
SUPPORTPILOT_OPEN_MODEL_API_KEY=...
SUPPORTPILOT_OPEN_CHALLENGER_ENDPOINT=...
SUPPORTPILOT_OPEN_CHALLENGER_MODEL=gemma4:e4b
ELEVENLABS_API_KEY=... # future benchmark only; voice remains disabled by default
SPEECHMATICS_API_KEY=... # future benchmark only; voice remains disabled by default
RESEND_API_KEY=...
INVITATION_FROM_EMAIL=...
ESCALATION_FROM_EMAIL=...
NEXT_PUBLIC_POSTHOG_KEY=...
NEXT_PUBLIC_POSTHOG_HOST=...
UPSTASH_REDIS_REST_URL=...
UPSTASH_REDIS_REST_TOKEN=...
SUPPORTPILOT_ALLOW_MEMORY_RATE_LIMITS=false
QSTASH_TOKEN=...
SUPPORTPILOT_INGESTION_WORKER_SECRET=...
SUPPORTPILOT_KNOWLEDGE_SOURCE_BUCKET=supportpilot-knowledge-sources
SUPPORTPILOT_INTEGRATION_WORKER_SECRET=...
SUPPORTPILOT_INTEGRATION_DELIVERY_MODE=queued # queued | inline
SUPPORTPILOT_RETENTION_WORKER_SECRET=...
SUPPORTPILOT_AUDIT_EVIDENCE_BUCKET=supportpilot-audit-evidence
SUPPORTPILOT_EVAL_WORKER_SECRET=...
SUPPORTPILOT_HEALTH_ALERT_SECRET=...
SUPPORTPILOT_HEALTH_ALERT_WEBHOOK_URL=...
SUPPORTPILOT_BILLING_RECONCILIATION_SECRET=...
SUPPORTPILOT_BILLING_RECONCILIATION_WEBHOOK_URL=...
SUPPORTPILOT_RATE_LIMIT_CHAT_PER_MINUTE=10
SUPPORTPILOT_RATE_LIMIT_WIDGET_CONFIG_PER_MINUTE=120
SUPPORTPILOT_RATE_LIMIT_WIDGET_SESSIONS_PER_5_MINUTES=30
SUPPORTPILOT_RATE_LIMIT_UPLOADS_PER_HOUR=20
SUPPORTPILOT_RATE_LIMIT_CUSTOMER_PORTAL_PER_5_MINUTES=30
SUPPORTPILOT_RATE_LIMIT_BILLING_WEBHOOKS_PER_MINUTE=120
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...
STRIPE_LAUNCH_MONTHLY_PRICE_ID=...
STRIPE_LAUNCH_ANNUAL_PRICE_ID=...
STRIPE_PRO_MONTHLY_PRICE_ID=...
STRIPE_PRO_ANNUAL_PRICE_ID=...
STRIPE_CUSTOMER_ID=...
SUPPORTPILOT_STRIPE_CUSTOMER_ID=...
STRIPE_BILLING_PORTAL_RETURN_URL=...

SUPPORTPILOT_APP_MODE defaults to demo for local previews. Set it to production for any deployed environment; production mode fails closed when Supabase URL, anon key, service-role key, invitation email delivery, or a persistent public rate-limit store is missing instead of silently returning demo auth/onboarding responses.

In Supabase mode, the proxy provides an early admin redirect and lib/auth/page.ts repeats the verified server-side check before any admin page loads data. Production admin, onboarding, portal, billing, and invitation actions also require Supabase auth.users.email_confirmed_at; unverified sessions are redirected to login with an explicit verification state. Admin pages resolve the caller's active workspace for metrics, tickets, sources, approvals, analytics, settings, and billing; an authenticated owner without a membership is allowed to reach the create-workspace step without reading the demo workspace.

Authenticated staff with more than one active membership can switch workspaces through the admin selector. GET /api/workspaces lists memberships and POST /api/workspaces/active validates each selection before storing only the workspace ID in an HTTP-only, same-site, secure-in-production cookie; proxy and server guards revalidate the membership on every request.

Password, magic-link, and reset flows use the shared internal redirect guard. Set NEXT_PUBLIC_SUPPORTPILOT_OAUTH_PROVIDERS=google,github only after the matching Supabase Auth providers are configured; enabled providers appear on staff sign-in and owner/customer entry points and return through /auth/callback without accepting external redirect targets.

SAML JIT membership mapping is disabled until the workspace SSO domain also appears in deployment-controlled SUPPORTPILOT_SAML_VERIFIED_DOMAINS. The callback accepts only Supabase SSO/SAML identities, rejects ambiguous domain ownership, and can assign only agent, analyst, or viewer; owner, admin, and manager access always requires an explicit privileged action. SUPPORTPILOT_SAML_REHEARSED_AT is evidence metadata, not proof by itself.

The database role boundary is enforced independently of the service layer. Active members can read permitted workspace data, agents can operate tickets and messages, managers can review AI decisions, and only owner/admin roles can mutate knowledge, ingestion/embedding jobs, memberships, workspace settings, policies, retention, and integrations. Profile-role self-escalation is blocked by migration 016_role_policy_hardening.sql; server-side Supabase requests are bounded by SUPPORTPILOT_SUPABASE_REQUEST_TIMEOUT_MS. npm run test:rls is the current local evidence; live multi-user RLS proof still requires a clean Supabase project.

Production customer portals require an authenticated, email-verified Supabase session. Portal workspace selection is server-resolved from an existing active portal identity, the configured SUPPORTPILOT_PORTAL_WORKSPACE_ID for first-time customers, or an active membership; arbitrary client-supplied workspace IDs are rejected before workspace data is loaded. Demo mode continues to use the seeded portal workspace.

/api/chat checks the current workspace plan snapshot before retrieval or generation. If the current billing period has reached the enforced conversation or AI reply limit, the request is escalated with audit/security events and no additional ai_run is created.

Public request rate limits use Upstash Redis REST when UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are configured. Without those variables, SupportPilot uses the local in-memory limiter for demos and tests, but production mode returns an unconfigured fail-closed limiter result unless SUPPORTPILOT_ALLOW_MEMORY_RATE_LIMITS=true is deliberately set for a controlled deployment. Chat, widget config, widget session creation, knowledge upload, portal ticket creation, customer ticket-message, and billing webhook boundaries are rate limited; user/workspace routes log rate_limited security events when blocked, while unsigned Stripe webhook floods are rejected before body parsing or signature verification. npm run test:rate-limit includes deterministic burst, customer-portal write, billing-webhook, missing-store, Redis-outage, and explicit-override checks before live load testing.

Knowledge ingestion uses EMBEDDING_PROVIDER when configured and falls back to deterministic 768-dimension embeddings for local demos. In SUPPORTPILOT_APP_MODE=production, deterministic embeddings are blocked unless SUPPORTPILOT_ALLOW_DETERMINISTIC_EMBEDDINGS=true is deliberately set for a controlled exercise. document_chunks store provider, model, version, dimensions, source version ID, content hash, and embedded timestamp so future provider migrations can be audited and re-run through /api/knowledge/reembed.

Workspace owners and admins can persist the model routing policy in Settings: managed_only keeps all generation on managed providers, local_preferred permits configured local runtimes for easy cited answers, and local_only_for_sensitive permits local routing only for sensitive or critical routes. The secure workspace default is managed_only. MODEL_ROUTER_DEFAULT=light is only the fallback for workspaces without an explicit policy.

Model connections, plan enforcement, health checks, circuit breaking, usage, and evaluation promotion are documented in MODEL_ORCHESTRATION.md. Starter workspaces require a customer key, Pro workspaces can use the shared Qwen3 4B pool for low-risk cited answers, and Enterprise workspaces can use a dedicated or customer-hosted OpenAI-compatible endpoint. Google Gemini free-tier keys are demo-only because free-tier content may be used to improve Google products and free capacity has no production guarantee; use paid-tier keys for production. Voice is a later, provider-neutral support channel and remains disabled until the text/RAG gate passes.

Knowledge uploads and site crawls now create knowledge_ingestion_jobs before extraction/chunking. Supabase-backed jobs store original upload bytes in the private supportpilot-knowledge-sources bucket, save only a supabase://bucket/path reference plus metadata in the job payload, and download the source in the worker before parsing. Small text uploads and bounded public website/sitemap crawls process immediately; large files and PDFs attempt QStash background delivery when QSTASH_TOKEN, NEXT_PUBLIC_APP_URL, and SUPPORTPILOT_INGESTION_WORKER_SECRET are configured, otherwise they fall back to the local synchronous demo path. A worker can call POST /api/knowledge/ingest/jobs/run with x-supportpilot-worker-secret to drain due queued jobs in batches. Jobs track status, attempts, retry timing, redacted extraction/storage errors, chunk counts, source URLs, and content-hash dedupe.

Integration delivery is queued by default. Approval-needed drafts and approval decisions create idempotent outbound_events for active Slack, generic webhook, Zendesk, or Intercom channels; delivery attempts write integration_deliveries with redacted response previews and error messages. Slack and generic webhook URLs must be public https endpoints and are rejected if they target localhost, private, or link-local hosts. Zendesk deliveries create private ticket comments; Intercom deliveries create admin notes. A worker can call POST /api/integrations/events/deliver with x-supportpilot-integration-secret when SUPPORTPILOT_INTEGRATION_WORKER_SECRET is configured to drain due queued retries in batches. Set SUPPORTPILOT_INTEGRATION_DELIVERY_MODE=inline only for controlled server-side demos where immediate external delivery is desired.

Production integration credentials are write-only. Migration 020_workspace_selection_vault_secrets.sql stores secret material in Supabase Vault, keeps only opaque Vault references in application tables, exposes rotation/use timestamps to the UI, and grants secret RPC execution only to service_role. Plaintext tokens, signing secrets, and Slack webhook URLs in integration configuration are rejected in production.

Approval queues calculate manager SLA metadata from existing AI run risk signals. Critical/legal/security/sensitive reviews target 60 minutes, billing/refund/angry/policy reviews target 4 hours, low-confidence/escalated reviews target 8 hours, and standard reviews target 24 hours. Queue data includes due time, minutes remaining, status, and reason so the handoff UI can sort and display overdue work without a schema migration.

Retention workflows use retention_settings to schedule conversation_cleanup and ai_log_cleanup jobs. Verified deletion requests create deletion_request jobs with non-PII proof hashes. Processed jobs redact aged ticket/message and AI-run content, remove deleted source documents with their vector chunks, and preserve audit-safe operational metadata. Retention job and evidence-export errors are redacted before persistence. A worker can call POST /api/security/retention/jobs/run with x-supportpilot-retention-secret when SUPPORTPILOT_RETENTION_WORKER_SECRET is configured to drain due queued jobs in batches. Audit evidence exports generate a typed readiness packet with period-scoped audit/security identifiers, an incident evidence feed, the RLS/deployment/access-review/vendor/backup evidence status, and an explicit external-evidence gap list. They hash the packet manifest, store previousArtifactHash plus evidenceChainHash to chain each successful export to the prior artifact, and, when Supabase is configured, store the JSON artifact in the private supportpilot-audit-evidence bucket with a supabase://bucket/path reference. Local demos keep a memory://audit-evidence/... artifact reference. This is SOC 2 readiness evidence, not a certification claim.

Golden-question evals can run from onboarding or an external scheduler. A scheduler can call POST /api/evals/golden/run with x-supportpilot-eval-secret when SUPPORTPILOT_EVAL_WORKER_SECRET is configured; each run updates golden_questions, stores a golden_eval_runs evidence row with a summary hash, and writes an audit log with pass/fail counts.

Production scheduler requirements are centralized in lib/ops/scheduler-manifest.ts and documented in OPERATIONS_RUNBOOK.md. The manifest can generate secret-safe request specs for a deployed base URL and workspace, including redacted headers, body payloads, cadence, owner, and missing setup fields for every launch-critical job. GET /api/health reports missing scheduled-operation secrets through the background_workers check, covering ingestion, integration delivery, retention cleanup, golden evals, domain rechecks, and billing reconciliation.

Custom widget domains start in pending status. Owners/admins add either a TXT record like supportpilot-verify=... or a CNAME to SUPPORTPILOT_DOMAIN_CNAME_TARGET at _supportpilot.<domain>, then call the verification endpoint. Widget config, signed widget sessions, and chat origin checks only allow domains after verification succeeds. The settings page shows domain health, stale checks, and the exact DNS challenge; scheduled jobs can call the recheck endpoint with x-supportpilot-domain-secret. When SUPPORTPILOT_DOMAIN_ALERT_WEBHOOK_URL is configured, rechecks send sanitized alerts for failing, stale, or blocked domains without exposing TXT tokens or observed DNS records; delivery failure messages also scrub webhook query strings, auth headers, and common secret patterns.

Stripe live-mode activation still requires creating real Stripe products/prices, setting the price IDs above, configuring the webhook endpoint with the matching STRIPE_WEBHOOK_SECRET, and running the test/live webhook matrix from Updates/21_Billing_Stripe_Lifecycle_Plan.md. In production mode, checkout and billing portal routes fail closed when Stripe secret, price ID, or customer mapping requirements are missing instead of returning demo billing sessions. Billing webhooks are rate limited before body parsing/signature verification, and failed webhook processing errors redact Stripe object IDs, URL query strings, auth headers, token assignments, and provider-style secret strings before storage or response. GET /api/billing/reconciliation and npm run test:billing provide the local pre-launch reconciliation rehearsal for configured price IDs, customer mappings, subscriptions, unpaid invoices, entitlements, and checkout drift. A scheduler can call POST /api/billing/reconciliation with x-supportpilot-billing-secret when SUPPORTPILOT_BILLING_RECONCILIATION_SECRET is set; failing/degraded reports send sanitized issue-code alerts to SUPPORTPILOT_BILLING_RECONCILIATION_WEBHOOK_URL when configured, and failed alert delivery errors are redacted before being returned.

GET /api/health returns secret-safe readiness state for uptime probes, including configuration checks and synthetic dependency probes for stats, chat retrieval/provider readiness, ticket draft data, and approval decision queues. POST /api/health can be called by a trusted monitor with x-supportpilot-health-secret when SUPPORTPILOT_HEALTH_ALERT_SECRET is set; degraded/failing snapshots send a sanitized incident payload to SUPPORTPILOT_HEALTH_ALERT_WEBHOOK_URL, while healthy snapshots and unconfigured webhooks are no-ops. Health alert delivery errors redact webhook URLs, bearer/basic auth values, token parameters, and provider-style secret strings.

Supabase

Apply all files in supabase/migrations/ in order, then run supabase/seed.sql for demo data. The migrations include enterprise support tables, productization tables, update-pass security/model-route tables, production auth/onboarding tables, Stripe billing lifecycle tables, embedding versioning/re-embedding job tables, background knowledge ingestion jobs, private knowledge-source storage, outbound integration event tables, retention/evidence job tables, private audit evidence artifact storage, chained audit evidence metadata, scheduled golden evidence runs, domain verification metadata, role-policy hardening, service-role-only workspace provisioning failure evidence, the portable deterministic seed embedding helper in migration 018, tenant model-routing policy in migration 019, Vault-backed integration secrets in migration 020, and identity governance/access reviews in migration 021. The seed includes 1 organization, 1 workspace, 4 staff memberships, 3 verified domains, widget config, 5 customers, 20 tickets, 10 knowledge articles, 5 policy docs, 5 escalated tickets, 10 AI draft replies, feedback, audit logs, escalation rules, approval policies, usage events, launch checklist rows, golden questions, missing-knowledge tasks, model route logs, grounding checks, policy evaluations, security events, retention settings, and read-only tool definitions.

The tracked local Supabase CLI config uses isolated ports 55421 (API), 55422 (database), 55423 (Studio), and 55424 (Mailpit) to avoid colliding with another local Supabase project.

npm run test:rls is the static migration/policy gate. npm run test:rls:live is the executable clean-project rehearsal; it is mutation-guarded by RUN_LIVE_RLS=1, creates isolated role fixtures, writes artifacts/rls-verification-YYYY-MM-DD.md, and cleans up its data. Follow RLS_VERIFICATION.md and only run it against a disposable local or staging project.

Default workspace key:

wk_demo_acmedesk

Seed staff password:

SupportPilot2026!

Verify

npm run typecheck
npm run lint
npm run audit:production
npm run test:billing
npm run test:rate-limit
npm run test:embeddings
npm run test:generation
npm run test:model-router
npm run test:reranker
npm run test:ingestion
npm run test:integrations
npm run test:retention
npm run test:domains
npm run test:ops
npm run test:evals
npm run test:rls
npm run test:rls:live # requires explicit RUN_LIVE_RLS=1 and rehearsal credentials
npm run test:enterprise
npm run test:production
npm run test:journeys
npm run test:health
npm run test:widget
npm run test:load
npm run test:e2e
npm run test:e2e:staging # requires STAGING_BASE_URL and real staging credentials
npm run build
git diff --check

npm run test:e2e runs the demo-mode Playwright browser gate across the marketing page, admin handoff routes, customer portal, widget routes, desktop/mobile overflow checks, navigation, and release screenshots. Install the local Chromium runtime once with npx playwright install chromium; CI installs Chromium and uploads the Playwright report and screenshots as artifacts. This does not replace live Supabase, Stripe, provider, scheduler, or staging RLS rehearsal.

GitHub Actions runs the same production gates plus critical journey contract checks and the Chromium-backed demo browser gate on pull requests and pushes to main through .github/workflows/ci.yml, then runs production builds. The workflow uploads static RLS, golden-question eval, Playwright report, and screenshot artifacts for release evidence.

Run npm run test:conversation against a dev server or live app to exercise /api/chat.

Docs

• ENTERPRISE_AUDIT.md - requirement status and evidence
• DESIGN.md - product UX and design system decisions
• ARCHITECTURE.md - Supabase, RAG, workflow, auth, observability
• SECURITY.md - RLS, roles, secrets, AI safety boundaries
• RLS_VERIFICATION.md - static RLS gate and clean Supabase project rehearsal checklist
• EVALS.md - automated and manual evaluation plan
• ROLE_ALIGNMENT.md - portfolio role mapping
• ROADMAP.md - production hardening and integrations
• OPERATIONS_RUNBOOK.md - production scheduler, worker, alerting, rotation, and launch-evidence runbook
• SOC2_READINESS_EVIDENCE.md - monthly readiness packet, access review, vendor, incident, deployment, and backup/restore templates
• LAUNCH_OWNERS.md - launch responsibility register; unassigned people remain explicit launch blockers
• CLIENT_SETUP.md - client rollout runbook
• INGEST.md - knowledge ingestion flow
• UPDATES_IMPLEMENTATION_TRACKER.md - compact implementation tracker for update passes
• MODEL_ORCHESTRATION.md - shared/BYOK model control plane, R0-R5 behavior, real-model gates, and voice boundary
• Updates/07_Enterprise_Design_System.md through Updates/12_Design_and_Model_Upgrade_Summary.md - enterprise readiness, security, workflow, agentic, and model-cost planning
• Updates/13_Design_Direction_Decision.md - locked LynAI visual direction, Agentra IA, and SupportPilot trust layer
• Updates/14_Landing_Page_IA_and_Copy.md - definitive landing IA, copy, pricing, FAQ, trust, and widget proof sections
• Updates/15_ChatGPT_Landing_Build_Prompt.md - self-contained landing HTML generation prompt used as implementation reference
• Updates/16_GoogleStitch_Dashboard_Prompts.md - admin, ticket, approval, knowledge, analytics, settings, security, billing, and widget screen prompts
• Updates/17_Feature_Set_Matrix.md - Launch, Pro, and Enterprise feature/tier matrix
• Updates/18_Redesign_Action_Plan.md - phased redesign and launch-readiness action plan
• Updates/19_Production_Readiness_Gap_Analysis.md - production gap matrix and priority stack
• Updates/20_Auth_and_Onboarding_Plan.md - Supabase Auth, RBAC, invite, portal identity, and onboarding plan
• Updates/21_Billing_Stripe_Lifecycle_Plan.md - Stripe checkout, webhook, subscription, entitlement, and dunning plan
• Updates/22_Integrations_and_Infra_Hardening_Plan.md - integrations, RLS proof, embeddings, rate limits, domains, retention, and local runtime plan
• Updates/23_Testing_and_QA_Strategy.md - production test pyramid, RLS matrix, Playwright journeys, evals, and CI gates
• Updates/24_Production_Execution_Roadmap.md - phased production-completion roadmap and go-live runbook
• Updates/25_Enterprise_Launch_Completion_Plan.md - remaining launch gates for production mode, tenancy, auth, billing, AI, widget, integrations, compliance, infrastructure, and QA
• Design Upgrade/ - LynAI-style SupportPilot marketing handoff, clean HTML prototype, and related design artifacts