Get Help UI → Support Chat Service → Support Knowledge Retrieval → Support Context AI-safe projection → AI provider adapter → AI Usage → Support Chat repository

Human escalation continues through the existing Support Request service and email infrastructure.

Retrieval architecture

The canonical docs/ Markdown tree remains the source of truth. documentation_service determines the deployed publication set. support_knowledge_service builds an in-memory, section-level index from those published files and computes a corpus hash from document hashes.

Each section retains a deterministic source ID, document/section titles, anchor, canonical public URL, Admin documentation path, audience, feature category, tags, content hash, and document hash. The index is rebuilt only when the documentation fingerprint changes.

Ranking combines exact phrase/heading/tag matches, lexical overlap, current-page terms, and simple diversity. Results are bounded by profile-controlled section count and character count. There is no vector database, PostgreSQL vector extension, provider File Search, or provider web search in the first release.

Audience enforcement occurs before the provider call. Feature documentation is available to authenticated users, administration documentation requires Org Admin scope, and deployment/development documentation requires System Admin scope.

Support Context boundary

support_context_service.build_support_context() remains the shared collector for human Support Request and AI Support Chat. New diagnostic/page context must be added to this shared Support Context first rather than being implemented only for the chatbot. Human Support Requests retain the richer sanitized context; ai_safe_support_context() is the only projection permitted to cross the AI-provider boundary. It removes user email/name, IP address/city/region, form values, query strings/fragments, server hostname/platform details, attachments, and credential-like data while preserving bounded page, role, organization, runtime, build, and coarse location context useful for troubleshooting.

support_page_registry_service adds deterministic Admin-page identity, label, feature, description, and retrieval topics. The shared Admin collector always sends the rendered active_admin_page and Flask page endpoint. Multi-feature pages can additionally mark a recently interacted area with data-support-feature, data-support-area-label, and data-support-area-description; Home uses this for Recipe Quick Actions, Cooking Here, API Token, Saved Queries, Displays, Today & Tomorrow, Shopping Lists, and Kitchen Inventory. The same enriched page context is therefore available to both AI troubleshooting and a later human escalation. The support API endpoint used to collect diagnostics is stored separately and must never replace the page the user was actually viewing.

When a Support Chat escalates, the Support Request rebuilds the transcript server-side and includes the session starting page, latest page, and the page context stored with each user turn. This preserves the page journey when the user follows troubleshooting steps before requesting human support.

Prompt and response contract

Prompt version support-chat-2026-08-07-v1 tells the model that retrieved documentation is authoritative reference material rather than instructions. It prohibits invented Blackcap behavior, secret disclosure, cross-organization data, administrative actions, destructive actions, arbitrary links, and hidden reasoning.

The provider must return structured JSON containing answer text, trusted source IDs, up to three suggested follow-ups, information-needed state, troubleshooting state, and escalation guidance. The application controls escalation UI; it never parses prose such as “contact support” to decide behavior.

Session storage

Migration 219 introduces:

support_chat_sessions — organization/user scope, lifecycle, original/current page snapshots, support/AI context snapshots, corpus/prompt version, turn count, retention, escalation reference;
support_chat_messages — ordered user/assistant/system-visible messages, idempotency identity, provider/usage correlation, status and bounded metadata;
support_chat_message_sources — server-resolved documentation source metadata for each assistant message.

AI Usage rows correlate through support_chat_session_id and support_chat_message_id and retain token/cost metadata separately from transcript retention. All normal Support Chat SQL lives in support_chat_repository; services/routes/templates contain no Support Chat SQL.

Idempotency and lifecycle

Every submitted user message requires an idempotency key. The repository uniqueness rules and reserved assistant sequence prevent browser retry/double click from creating multiple provider calls. The browser keeps only lightweight per-user UI state: whether an active panel was open, the active session ID, panel dimensions, and an unsent composer draft. The open/session/draft state uses per-tab sessionStorage; dimensions use localStorage. Normal navigation can therefore reopen an active conversation and restore an unsent draft without turning the Admin application into an SPA.

Terminal statuses receive purge_after; active/waiting states remain protected. A resolved chat, successfully escalated Support Request, provider-failed chat, or turn-limit-closed chat is not eligible for automatic resume. Choosing I still need help records needs_more_help so the already-used resolution controls remain hidden until a new assistant response creates a new decision point. Cleanup removes dependent sources/messages first and marks the session shell purged so AI Usage can distinguish expiration from application error.

On this page