descrybe/docs/support-auto/03-kb-auto-reply.md

03 — KB / FAQ auto-reply (agent 3/10)

Goal

Platform knowledge base + reply templates with a sync lexical matcher that can post a labeled author_role=system first response when confidence clears the threshold. No LLM on this path (agent 4 owns TryAutoReplyLLM).

Schema

Migration: apps/api/sql/schema/032_support_kb_auto_reply.sql

Table	Purpose
support_kb_articles	Published FAQ articles (slug, title, body_md, keywords, intent_keys, category_slugs, priority_weight)
support_reply_templates	Canned replies with same match fields; placeholders allowlist: {{subject}}, {{category}}
support_auto_config	Singleton: enabled, faq_enabled, match_confidence_threshold (default 0.78), retry_on_first_customer_reply

Ticket/message auto columns (auto_reply_*, is_auto_reply, …) come from 031_support_ticket_detail.sql (agent 5). Do not re-ALTER them here.

Service API

Package: apps/api/internal/support

Symbol	Role
MatchAutoReply(ctx, ticket) → MatchAutoReplyResult	Scores corpus; {matched, confidence, reply_body, article_id, template_id, kind} — never posts, never LLM
PostMatchedAutoReply	Posts system message when confidence >= threshold; sets status pending, auto_reply_status=matched; notifies auto_reply
MaybeAutoReplyOnCreate	Stage A after create (respects config)
MaybeAutoReplyOnCustomerReply	Optional retry when retry_on_first_customer_reply; handoff if prior public auto exists
KB / template CRUD	Create/Update/Delete/List/Get for articles + templates
GetAutoConfig / UpdateAutoConfig	FAQ switchboard

Matching: keyword overlap (0.70) + intent phrase (0.15) + category boost (0.15) + small priority weight. Secrets redacted before score (RedactSecretsForMatch). Corpus cached ~60s; invalidated on admin writes.

HTTP (platform admin)

Mounted under RequirePlatformAdmin:

Method	Path
GET/POST	/api/admin/support/kb/articles
GET/PATCH/DELETE	/api/admin/support/kb/articles/{id}
GET/POST	/api/admin/support/templates
GET/PATCH/DELETE	/api/admin/support/templates/{id}
GET/PUT	/api/admin/support/auto-config

Customer create (POST /api/support/tickets) calls MaybeAutoReplyOnCreate after successful create. Customer reply calls MaybeAutoReplyOnCustomerReply (no-op unless retry flag).

Defaults / ops

• Master enabled=false until admin turns FAQ auto on.
• Enable + publish articles/templates + set threshold → create a ticket whose subject/body hits keywords → expect system message with footer “Automated answer from help center”.
• Below threshold → auto_reply_status=skipped (agent 4 may enqueue AI).

Tests

• Unit: apps/api/internal/support/match_auto_reply_test.go (scoring, redaction, placeholders, footer).
• Auth probes include KB/template/auto-config paths in support_auth_test.go.

Coordination

• Agent 4: on match miss / low confidence → TryAutoReplyLLM async; reuse message auto_* columns.
• Agent 5: ticket detail fields + activity; FAQ posts ActivityAutoReply via insertActivity.
• Agent 6: admin UI for KB + auto-config.
• Agent 10: migrate 032_*, end-to-end verify.