{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Descrybe v2 Support Auto-Response + Rich Ticket Contract",
  "version": "02.0.0-design",
  "status": "design-only",
  "related": [
    "docs/support-auto/02-contract.md",
    "docs/support-auto/01-inventory.md",
    "docs/support-auto/01-extension-points.json",
    "docs/admin-roles-support/11-support-design.md",
    "docs/admin-roles-support/11-support-api-contract.json"
  ],
  "inventory_note": "Reconciled with agent-1 01-inventory + 01-extension-points; Create post-commit is the preferred orchestrator hook.",
  "discovered_symbols": {
    "ai_gate": {
      "symbol": "TryAutoReplyLLM",
      "path": "apps/api/internal/support/ai_auto_reply.go",
      "behavior_today": "returns ErrAIAutoReplyDisabled"
    },
    "create_hook": {
      "symbol": "Create",
      "path": "apps/api/internal/support/tickets.go",
      "line": 252,
      "note": "Post-commit: content matcher then optional TryAutoReplyLLM; never Completer directly"
    },
    "ai_role_constant": {
      "symbol": "AIRoleSupport",
      "value": "support",
      "path": "apps/api/internal/platformsettings/types.go"
    },
    "ai_resolve": {
      "symbol": "ResolveAIConfig",
      "path": "apps/api/internal/platformsettings/ai_configs.go"
    },
    "completer": {
      "symbol": "ResolveCompleterForRole",
      "role": "RoleSupport",
      "path": "apps/api/internal/aiprovider/roles.go",
      "notes": "Platform role only; no env fallback when unset"
    },
    "admin_api": {
      "path": "/api/admin/settings",
      "field": "ai_roles.support",
      "handlers": "apps/api/internal/httpapi/admin_settings_handlers.go",
      "web": [
        "apps/web/src/lib/admin-ai-roles.ts",
        "apps/web/src/lib/admin-platform-settings.ts",
        "apps/web/src/routes/admin/settings/+page.svelte"
      ]
    },
    "ticket_type": {
      "symbol": "Ticket",
      "path": "apps/api/internal/support/types.go"
    },
    "schema": [
      "apps/api/sql/schema/025_support_center.sql",
      "apps/api/sql/schema/027_capabilities_support_perf.sql",
      "apps/api/sql/schema/029_staff_roles.sql",
      "apps/api/sql/schema/030_support_desk.sql"
    ],
    "docs_ask_pattern": {
      "component": "apps/web/src/lib/components/docs/DocsAskGuide.svelte",
      "rule": "content match pattern only; never AIRoleSupport"
    },
    "jobs_pattern": {
      "symbol": "EnqueueProcessingJob",
      "path": "apps/api/internal/jobs/river.go",
      "notes": "River deferred; Postgres pending + worker poller"
    },
    "rate_limit_pattern": {
      "path": "apps/api/internal/httpapi/ratelimit.go"
    }
  },
  "conventions": {
    "timestamps": "RFC3339 UTC",
    "ids": "UUID string",
    "errors": {
      "shape": { "error": "string", "code": "string?" }
    },
    "additive_only": true
  },
  "enums": {
    "ticket_status": ["open", "pending", "resolved", "closed"],
    "ticket_priority": ["low", "normal", "high"],
    "ticket_category_seed": ["billing", "bug", "account", "other"],
    "author_role": ["user", "agent", "system"],
    "auto_source": ["kb", "template", "ai"],
    "auto_reply_status": [
      "none",
      "matched",
      "ai_draft",
      "ai_sent",
      "skipped",
      "failed",
      "handed_off"
    ],
    "ai_delivery": ["draft", "auto_send"],
    "match_kind": ["kb_article", "template", "none"],
    "notification_kind_additive": ["auto_reply"],
    "support_auto_job_status": ["pending", "running", "done", "failed"]
  },
  "types": {
    "CustomerContextSnapshot": {
      "type": "object",
      "required": ["captured_at", "company_id", "user_id"],
      "properties": {
        "captured_at": { "type": "string", "format": "date-time" },
        "company_id": { "type": "string", "format": "uuid" },
        "company_name": { "type": "string" },
        "plan_slug": { "type": ["string", "null"] },
        "user_id": { "type": "string", "format": "uuid" },
        "user_email": { "type": "string" },
        "user_name": { "type": ["string", "null"] },
        "locale": { "type": ["string", "null"] },
        "timezone": { "type": ["string", "null"] },
        "related_product": {
          "type": "object",
          "properties": {
            "id": { "type": ["string", "null"], "format": "uuid" },
            "sku": { "type": ["string", "null"], "maxLength": 128 },
            "title": { "type": ["string", "null"] }
          }
        },
        "signals": {
          "type": "object",
          "properties": {
            "open_ticket_count": { "type": "integer", "minimum": 0 },
            "last_ticket_category": { "type": ["string", "null"] }
          }
        }
      },
      "constraints": {
        "filled_server_side": true,
        "immutable_after_create": true,
        "max_bytes": 4096,
        "forbidden": [
          "api_keys",
          "smtp_secrets",
          "byok_material",
          "payment_tokens",
          "other_tenant_data"
        ]
      }
    },
    "SupportTicketRich": {
      "description": "Additive fields on SupportTicket from 11-contract",
      "extends": "docs/admin-roles-support/11-support-api-contract.json#/types/SupportTicket",
      "properties": {
        "tags": {
          "type": "array",
          "items": { "type": "string", "maxLength": 40 },
          "maxItems": 10
        },
        "related_product_id": { "type": ["string", "null"], "format": "uuid" },
        "related_sku": { "type": ["string", "null"], "maxLength": 128 },
        "category": {
          "type": "string",
          "description": "Taxonomy slug; seeds billing|bug|account|other; admin may add active slugs"
        },
        "customer_context": {
          "oneOf": [
            { "$ref": "#/types/CustomerContextSnapshot" },
            { "type": "null" }
          ],
          "description": "Staff detail full; customer detail may omit signals"
        },
        "auto_reply_disabled": { "type": "boolean", "default": false },
        "auto_reply_status": { "$ref": "#/enums/auto_reply_status" },
        "auto_reply_attempted_at": {
          "type": ["string", "null"],
          "format": "date-time"
        },
        "auto_reply_message_id": {
          "type": ["string", "null"],
          "format": "uuid"
        }
      }
    },
    "SupportMessageAuto": {
      "description": "Additive fields on SupportMessage",
      "properties": {
        "is_auto_reply": { "type": "boolean", "default": false },
        "auto_source": {
          "oneOf": [{ "$ref": "#/enums/auto_source" }, { "type": "null" }]
        },
        "auto_confidence": {
          "type": ["number", "null"],
          "minimum": 0,
          "maximum": 1
        },
        "auto_ref_type": {
          "type": ["string", "null"],
          "enum": ["kb_article", "template", null]
        },
        "auto_ref_id": { "type": ["string", "null"], "format": "uuid" }
      },
      "labeling": {
        "author_role": "system",
        "author_user_id": null,
        "customer_badge": "Automated|AI-assisted",
        "never_impersonate_human_agent": true
      }
    },
    "SupportCategory": {
      "type": "object",
      "required": ["slug", "label", "is_active"],
      "properties": {
        "slug": { "type": "string", "maxLength": 32 },
        "label": { "type": "string", "maxLength": 80 },
        "parent_slug": { "type": ["string", "null"] },
        "sort_order": { "type": "integer" },
        "is_active": { "type": "boolean" },
        "match_intents": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "SupportKbArticle": {
      "type": "object",
      "required": ["id", "slug", "title", "body_md", "is_published"],
      "properties": {
        "id": { "type": "string", "format": "uuid" },
        "slug": { "type": "string" },
        "title": { "type": "string", "maxLength": 200 },
        "body_md": { "type": "string", "maxLength": 20000 },
        "category_slugs": { "type": "array", "items": { "type": "string" } },
        "keywords": { "type": "array", "items": { "type": "string" } },
        "intent_keys": { "type": "array", "items": { "type": "string" } },
        "is_published": { "type": "boolean" },
        "priority_weight": { "type": "integer", "default": 0 }
      }
    },
    "SupportReplyTemplate": {
      "type": "object",
      "required": ["id", "name", "body", "is_active"],
      "properties": {
        "id": { "type": "string", "format": "uuid" },
        "name": { "type": "string", "maxLength": 120 },
        "body": { "type": "string", "maxLength": 10000 },
        "category_slugs": { "type": "array", "items": { "type": "string" } },
        "keywords": { "type": "array", "items": { "type": "string" } },
        "intent_keys": { "type": "array", "items": { "type": "string" } },
        "is_active": { "type": "boolean" },
        "placeholders_allowlist": ["subject", "related_sku", "company_name"]
      }
    },
    "MatchResult": {
      "type": "object",
      "required": ["kind", "confidence"],
      "properties": {
        "kind": { "$ref": "#/enums/match_kind" },
        "ref_id": { "type": ["string", "null"], "format": "uuid" },
        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
        "body": { "type": ["string", "null"] },
        "label": { "type": "string" }
      }
    },
    "AiAssistResult": {
      "type": "object",
      "required": ["body", "confidence", "handoff"],
      "properties": {
        "body": { "type": "string", "maxLength": 10000 },
        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
        "handoff": { "type": "boolean" },
        "citations": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "SupportAutoSettings": {
      "type": "object",
      "required": ["enabled"],
      "properties": {
        "enabled": { "type": "boolean", "default": false },
        "faq_enabled": { "type": "boolean", "default": true },
        "ai_enabled": { "type": "boolean", "default": false },
        "match_confidence_threshold": {
          "type": "number",
          "default": 0.78,
          "minimum": 0.5,
          "maximum": 0.95
        },
        "ai_confidence_threshold": {
          "type": "number",
          "default": 0.65,
          "minimum": 0.5,
          "maximum": 0.95
        },
        "ai_delivery": {
          "$ref": "#/enums/ai_delivery",
          "default": "draft"
        },
        "ai_use_global_support_role": { "type": "boolean", "default": true },
        "ai_provider_override": { "type": ["string", "null"], "maxLength": 64 },
        "ai_model_override": { "type": ["string", "null"], "maxLength": 128 },
        "ai_base_url_override": {
          "type": ["string", "null"],
          "maxLength": 512
        },
        "rate_limit_per_company_per_hour": {
          "type": "integer",
          "default": 10,
          "minimum": 1
        },
        "rate_limit_platform_per_minute": {
          "type": "integer",
          "default": 30,
          "minimum": 1
        },
        "retry_on_first_customer_reply": {
          "type": "boolean",
          "default": false
        }
      },
      "notes": "Overrides change provider/model/base_url only; API key always from ai_roles.support"
    }
  },
  "pipeline": {
    "name": "support_auto_first_response",
    "entry_triggers": [
      {
        "event": "ticket_created",
        "required": true
      },
      {
        "event": "customer_first_reply_without_prior_auto",
        "required": false,
        "gate": "settings.retry_on_first_customer_reply"
      }
    ],
    "preconditions": [
      "settings.enabled == true",
      "ticket.auto_reply_disabled == false",
      "ticket.status in open|pending",
      "no prior public is_auto_reply message OR retry flag allows"
    ],
    "stages": [
      {
        "id": "A_faq_template_match",
        "mode": "sync",
        "max_cpu_ms": 50,
        "llm": false,
        "when": "settings.faq_enabled",
        "action_on_hit": {
          "condition": "confidence >= settings.match_confidence_threshold",
          "post_message": {
            "author_role": "system",
            "is_internal_note": false,
            "is_auto_reply": true,
            "auto_source": "kb|template"
          },
          "ticket_status": "pending",
          "auto_reply_status": "matched",
          "assign_agent": false,
          "notify_kind": "auto_reply"
        },
        "action_on_miss": "continue_to_B"
      },
      {
        "id": "B_ai_assist",
        "mode": "async_job",
        "job_kind": "support_auto_reply",
        "llm_gate": "support.TryAutoReplyLLM",
        "completer": "aiprovider.ResolveCompleterForRole(RoleSupport)",
        "when": "settings.ai_enabled && ai_roles.support configured",
        "prompt": {
          "inputs": [
            "redacted_subject",
            "redacted_body",
            "category",
            "tags",
            "related_sku",
            "kb_snippets_top_n",
            "sanitized_customer_context"
          ],
          "output_schema": "AiAssistResult",
          "rules": [
            "answer only from snippets + ticket",
            "no cross-tenant data",
            "no inventing billing facts",
            "handoff=true when unsure"
          ]
        },
        "delivery": {
          "draft": {
            "is_internal_note": true,
            "auto_reply_status": "ai_draft",
            "notify_customer": false,
            "notify_staff": true
          },
          "auto_send": {
            "is_internal_note": false,
            "auto_reply_status": "ai_sent",
            "ticket_status": "pending",
            "notify_kind": "auto_reply",
            "condition": "confidence >= ai_confidence_threshold && handoff == false"
          }
        },
        "on_failure": "human_handoff"
      }
    ],
    "human_handoff": {
      "set": {
        "auto_reply_status": "handed_off",
        "auto_reply_disabled": true
      },
      "triggers": [
        "ai_handoff_true_or_low_confidence",
        "ai_provider_error_or_unset",
        "ai_rate_limited",
        "customer_reply_after_public_auto",
        "staff_public_reply_or_explicit_disable"
      ],
      "optional_internal_note": "Needs human review",
      "keep_claimable": true,
      "assign_agent": false
    }
  },
  "schema_deltas_sketch": {
    "support_tickets_additive": [
      "tags TEXT[] NOT NULL DEFAULT '{}'",
      "related_product_id UUID NULL",
      "related_sku TEXT NULL",
      "customer_context JSONB NULL",
      "auto_reply_disabled BOOLEAN NOT NULL DEFAULT false",
      "auto_reply_status TEXT NOT NULL DEFAULT 'none'",
      "auto_reply_attempted_at TIMESTAMPTZ NULL",
      "auto_reply_message_id UUID NULL"
    ],
    "support_messages_additive": [
      "is_auto_reply BOOLEAN NOT NULL DEFAULT false",
      "auto_source TEXT NULL",
      "auto_confidence REAL NULL",
      "auto_ref_type TEXT NULL",
      "auto_ref_id UUID NULL"
    ],
    "new_tables": [
      "support_categories",
      "support_kb_articles",
      "support_reply_templates",
      "support_auto_jobs"
    ],
    "category_check": "Replace hard CHECK with taxonomy table + app validation; seed billing/bug/account/other"
  },
  "endpoints_additive": [
    {
      "id": "customer.create_ticket_rich",
      "method": "POST",
      "path": "/api/support/tickets",
      "auth": "customer",
      "body_additive": {
        "tags": { "type": "string[]", "optional": true, "maxItems": 10 },
        "related_product_id": { "type": "uuid", "optional": true },
        "related_sku": { "type": "string", "optional": true, "maxLength": 128 }
      },
      "side_effects": [
        "server fills customer_context",
        "after commit: Stage A sync; maybe enqueue Stage B",
        "HTTP must not await LLM"
      ]
    },
    {
      "id": "staff.patch_auto_fields",
      "method": "PATCH",
      "path": "/api/admin/support/tickets/{id}",
      "auth": "support_desk",
      "body_additive": {
        "auto_reply_disabled": { "type": "boolean", "optional": true },
        "tags": { "optional": true },
        "related_product_id": { "optional": true },
        "related_sku": { "optional": true },
        "category": { "optional": true }
      }
    },
    {
      "id": "admin.support_auto_settings",
      "method": "GET|PUT",
      "path": "/api/admin/settings",
      "auth": "platform_admin",
      "field": "support_auto",
      "schema_ref": "#/types/SupportAutoSettings"
    },
    {
      "id": "admin.kb_crud",
      "method": "GET|POST|PATCH|DELETE",
      "path": "/api/admin/support/kb/articles",
      "auth": "platform_admin"
    },
    {
      "id": "admin.templates_crud",
      "method": "GET|POST|PATCH|DELETE",
      "path": "/api/admin/support/templates",
      "auth": "platform_admin"
    },
    {
      "id": "admin.categories_crud",
      "method": "GET|POST|PATCH|DELETE",
      "path": "/api/admin/support/categories",
      "auth": "platform_admin"
    }
  ],
  "security": {
    "tenant_isolation": [
      "All ticket queries filter company_id",
      "related_product_id must belong to ticket company_id",
      "Prompts never include other companies' tickets",
      "KB is platform content only — not tenant data"
    ],
    "redaction": {
      "before_match_and_ai": true,
      "patterns": [
        "api_keys",
        "bearer_tokens",
        "sk-_openai_style",
        "aws_keys",
        "pem_private_keys",
        "connection_strings"
      ],
      "replacement": "[REDACTED]"
    },
    "rate_limits": {
      "faq_match": "unlimited_within_cpu_budget",
      "ai_per_company_per_hour": "settings.rate_limit_per_company_per_hour",
      "ai_platform_per_minute": "settings.rate_limit_platform_per_minute",
      "on_exceed": "skip_ai_handoff_create_still_201"
    },
    "per_ticket_disable": {
      "field": "auto_reply_disabled",
      "actors": ["support_desk", "auto_on_handoff"]
    },
    "secrets": [
      "Never log ResolveAIConfig API keys",
      "Overrides do not store a second API key",
      "customer_context must not contain secrets"
    ],
    "docs_ask_invariant": "Guided /docs Ask must never use AIRoleSupport or AIRoleDocsAPI"
  },
  "performance": {
    "faq_match": "sync_bounded",
    "ai_assist": "async_job_only",
    "create_http": "no_llm_await",
    "kb_cache_ttl_seconds": 60,
    "list_endpoints": "omit_full_customer_context",
    "indexes": [
      "GIN tags",
      "auto_reply_status",
      "support_auto_jobs (status, created_at)",
      "kb keywords GIN"
    ]
  },
  "contracts_preserved": [
    "Existing customer ticket create fields remain valid without tags/SKU",
    "author_role enum unchanged; system used for auto",
    "ai_roles.support admin shape unchanged",
    "Desk claim/visibility from agent 11 unchanged",
    "TryAutoReplyLLM remains sole LLM ticket gate"
  ],
  "breaking_soft": [
    {
      "change": "Category taxonomy expands beyond CHECK four",
      "migration": "Seed four; app validates active slugs; historical inactive slugs readable"
    },
    {
      "change": "notification kind auto_reply",
      "migration": "Widen support_notifications kind CHECK"
    }
  ],
  "test_matrix": [
    {
      "case": "faq_above_threshold",
      "expect": "public system auto message; status pending; no AI job"
    },
    {
      "case": "faq_below_threshold_ai_draft",
      "expect": "async job; internal note; customer no public auto"
    },
    {
      "case": "ai_auto_send",
      "expect": "public labeled AI message when conf ok"
    },
    {
      "case": "ai_unset_role",
      "expect": "handoff; TryAutoReplyLLM fail closed"
    },
    {
      "case": "cross_tenant_product_id",
      "expect": "400/ignore product; never leak"
    },
    {
      "case": "secret_in_body",
      "expect": "redacted before AI; not in logs"
    },
    {
      "case": "customer_reply_after_auto",
      "expect": "auto_reply_disabled; no second AI"
    },
    {
      "case": "staff_disable_auto",
      "expect": "orchestrator no-op"
    },
    {
      "case": "rate_limit_ai",
      "expect": "handoff; create 201"
    },
    {
      "case": "master_switch_off",
      "expect": "no match post; no job"
    }
  ],
  "assumptions": [
    "MVP matcher is lexical not embeddings (Docs Ask is pattern inspiration only)",
    "Support AI uses platform ai_roles.support only (no tenant BYOK)",
    "FAQ match does not auto-assign agents",
    "Extend TryAutoReplyLLM rather than a parallel LLM entry point",
    "Product gate is support_auto.enabled AND ai_roles.support.enabled (inventory 4.3)",
    "No plan-permission key for auto-reply in MVP (platform admin settings only)",
    "support_auto settings stored in platform JSON alongside ai_roles"
  ]
}