fix

apps/api/internal/httpapi/v1_openapi_test.go

@@ -467,6 +467,44 @@ func TestV1OpenAPIYAMLOmitsInternalPromptWording(t *testing.T) {
 	}
 }
 
+func TestV1OpenAPIYAMLDocumentsAIDescriptionHTML(t *testing.T) {
+	t.Parallel()
+
+	doc := string(v1OpenAPIYAML)
+	for _, needle := range []string{
+		"AI descriptions (HTML body, not a short blurb)",
+		"description_template (description formula)",
+		"one- or two-sentence",
+		"<h1>VOX electric cooker EHT 6020 WG</h1>",
+		"<h2>Key features</h2>",
+	} {
+		if !strings.Contains(doc, needle) {
+			t.Fatalf("openapi missing AI description contract text %q", needle)
+		}
+	}
+
+	root := mustParseOpenAPIRoot(t, v1OpenAPIYAML)
+	comps, _ := root["components"].(map[string]any)
+	examples, _ := comps["examples"].(map[string]any)
+	completed, _ := examples["ProcessCompletedExample"].(map[string]any)
+	val, _ := completed["value"].(map[string]any)
+	data, _ := val["data"].(map[string]any)
+	items, _ := data["items"].([]any)
+	if len(items) == 0 {
+		t.Fatal("ProcessCompletedExample: expected items")
+	}
+	item, _ := items[0].(map[string]any)
+	desc, _ := item["description"].(string)
+	for _, tag := range []string{"<h1>", "<p>", "<h2>", "<ul>", "<li>"} {
+		if !strings.Contains(desc, tag) {
+			t.Fatalf("ProcessCompletedExample description must include %s (got %q)", tag, desc)
+		}
+	}
+	if len(desc) < 800 {
+		t.Fatalf("ProcessCompletedExample description too short (%d chars); expected full AI HTML body", len(desc))
+	}
+}
+
 func TestV1OpenAPIYAMLProcessItemCompletedExamplesOmitLeakyShape(t *testing.T) {
 	t.Parallel()
 	root := mustParseOpenAPIRoot(t, v1OpenAPIYAML)