docs: how tutor diagrams work, measured accuracy and cost

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/architecture.md

@@ -176,6 +176,27 @@ temperature و با `OPENAI_CHAT_REASONING_EFFORT` صدا زده می‌شوند
 `/api/health` آن را در `integrations.aiProvider` و `warnings` نشان می‌دهد.
 پیش‌تر `openai: true` فقط یعنی «کلید تنظیم شده».
 
+### شکل در جواب (پرامپتِ `tutor-v10-shape-anchor`، ۲۰۲۶-۰۹-۲۹)
+
+مدل HTML یا SVG نمی‌نویسد. در پایانِ جوابِ شکل‌دار یک بلوکِ کوتاهِ `<diagram>{JSON}</diagram>` می‌گذارد
+که فقط **توصیف** است («مثلثی با AB = 6، AC = 8 و زاویه‌ی قائمه در A»). فرانت (`src/diagram/`) از روی
+آن SVG می‌سازد و هر عددی را که قابلِ حساب است خودش حساب می‌کند: رأس‌های مثلث با قانونِ سینوس و
+کسینوس، ریشه و رأسِ نمودار با نصف‌کردنِ بازه، مماس با مشتقِ عددی، رأس‌های چندضلعیِ منتظم.
+
+| لایه | کجا | کار |
+|---|---|---|
+| تشخیص | `diagram.hint_for` / `follow_up_hint_for` / `asked_hint_for` | کنارِ سوال فقط بخشِ مربوطِ کاتالوگ می‌رود: کلمه‌ی موضوعی (یا نامِ درس)، سوالِ شکل‌دارِ قبلی، یا درخواستِ صریحِ «شکلش رو بکش» (کلِ کاتالوگ). سوالِ حسابی هیچ |
+| جدا کردن | `diagram.StreamSplitter` / `extract` | بلوک پیش از `mathtext` از متن جدا می‌شود؛ JSON هیچ‌وقت به حباب نمی‌رسد |
+| تعمیر | `diagram._repair` / `_loads` / `_normalize` | لغزش‌های واقعیِ مدل: رقمِ فارسی، `2*pi`، `-2 * 3.14`، گیومه‌ی جاافتاده، کلیدِ تکراری، `"kind":"trapezoid"` |
+| وارسی | `diagram.validate` | فهرستِ سفیدِ نوع و کلید و رنگ، عددِ محدود، برچسبِ کوتاه؛ تکه‌ی خراب حذف، شکلِ بی‌محتوا `None` |
+| نگهبانِ معنا | `diagram.fits` | ساعتِ دیواری فقط برای سوالی که واقعاً درباره‌ی خواندنِ ساعت است |
+| ذخیره | `Message.diagram` | در `done`ِ SSE و تاریخچه می‌آید |
+
+سنجش (۶۴ مسئله‌ی تصادفیِ کتاب، ۸ از هر پایه، وارسیِ چشمیِ تک‌تک): ۴۰ درست، ۱۲ قابلِ قبول، ۷ غلط،
+۵ بی‌شکل؛ برآوردِ ۹۵٪ برای شکلِ درست ۵۰–۷۳٪ و برای شکلِ غلط ۵–۲۱٪. هزینه‌ی اضافه‌ی شکل با نرخِ
+رسمی ۰٫۰۰۰۳ تا ۰٫۰۰۰۸ دلار در هر جواب؛ کارِ سرور حدودِ ۰٫۴ میلی‌ثانیه. آزموده نشده: مدل‌های دیگر.
+برای تستِ مسیر بی‌خرج، `tools/fake_openai.py` جای GapGPT می‌نشیند.
+
 ## ساختِ آزمون
 
 اپ در سطحِ **نود** بازی می‌شود (جزیره روی نقشه)، ولی سوال‌ها به **درس** وصلند —