Skip to main content

ADR-0014 — Conversational knowledge authoring (chat-only writes)

Date: 2026-06-10 Status: Accepted Relates to: ADR-0013 (Phase-0 knowledge answers), ADR-0005 (safety_class confirmation gating), ADR-0010 D9 (prompt-cache invariant)

Context​

ADR-0013 shipped the Phase-0 "no-RAG RAG": per-tenant knowledge_snippets feed the answer-shaper via fetch_snippets(intent), capped at ~20 snippets/~1500 tokens with the knowledge_overflow WARN as the Phase-1 graduation trigger. Its only authoring path was scripts/seed_knowledge.py — operator-run, no product surface. Real tenants (M13 beta) cannot teach the assistant anything.

During the onboarding-milestone review (2026-06-10) Adrian rejected both a wizard FAQ step and a Settings editing tab in favour of chat-authored knowledge — the purest expression of the conversational-first thesis — with a read-only dashboard view for inspection.

Decision​

  1. Writes are chat-only. Three admin verbs on the M11 command rail: /add-faq "<q>" "<a>" [--category …] [--lang en|sw], /list-faqs, /remove-faq <n|fragment>. Mutations use the existing two-turn YES/NO Redis confirmation (ADR-0005 safety_class); /list-faqs is read-only and unconfirmed. Removal is a soft-delete (is_active=false).
  2. The dormant NL router goes live for the dashboard chat. Non-slash {type:"command"} text routes through dispatch_admin_text (M11), activating natural language for every admin verb. NL-initiated mutations keep the two-turn confirm regardless of classifier confidence — the ≥0.9 auto-execute band applies to the slash synthesis, never to skipping the YES/NO gate.
  3. Read-only Knowledge UI. A dashboard panel lists active snippets + cap usage + service descriptions, each row deep-linking to Chat for changes. One GET /api/v1/admin/knowledge; no write endpoints.
  4. The cap advises, never refuses. Crossing ~20 snippets/~1500 tokens appends advice to the confirmation prompt; the knowledge_overflow WARN remains the observable Phase-1 graduation trigger (unchanged from ADR-0013).
  5. Audit = structured logging for v1. catalog_audits.service_id is NOT NULL + FK'd to services, so FAQ mutations cannot ride it without a migration. FAQ verbs emit the same admin.command.executed structlog event family with full payloads; a dedicated knowledge_audits table is deferred until a compliance requirement names it.

Consequences​

  • ADR-0013's "no conversational/dashboard authoring in P0" stance is amended: conversational authoring is in; dashboard authoring stays out.
  • The prompt-cache invariant is untouched — snippets continue to ride the answer-shaper user template only.
  • fetch_snippets (the read path) is unchanged; soft-deleted snippets drop out via the existing is_active filter.
  • Tenant isolation is inherited from the ADR-0002 search_path session; the verbs add no cross-tenant surface.
  • The WhatsApp-admin inbound path remains stubbed; this ADR covers the dashboard chat only.