AI teaching assistant + metered AI wallet & credit top-ups

Why / Context

PRD §7.2A: a 24/7 AI teaching assistant trained on each course's content is becoming a baseline expectation (Euron's EURI, Graphy's AI Brain). The teardown's STEAL list adds the monetization primitive: metered AI usage as a wallet (daily allowance + paid top-up), which "turns a cost center into an upsell lever instead of an unbounded expense" — exactly how Euron prices its 51-model gateway. We deliberately do NOT expose a raw model picker (teardown SKIP list) — task-specific AI only.

Schema already in place — NO migration required

• AiWallet (balanceCredits, dailyAllowance, allowanceRefreshedAt)
• AiCreditPack + CommerceItemType.AI_CREDIT_PACK — top-ups flow through the normal cart/checkout
• AiUsageEvent(feature: AI_TUTOR, model, tokens, credits, costMicrosUsd)
• AiConversation / AiMessage (course/lesson/project-instance scoped)
• Plan entitlements already carry aiDailyCredits (50/150/300 seeded for Learn/Mentor/Career)

Implementation plan

1. RAG indexing pipeline (src/lib/ai/indexing.ts): chunk course content (lesson articles, video transcripts from Fermion transcription, quiz explanations) → pgvector embeddings (enable vector extension via an ADDITIVE migration — allowed; no core-table changes) with per-course namespace.
2. Tutor service (src/lib/ai/tutor.ts): retrieval + Claude API answer generation grounded in the creator's own content and teaching style; check current model ids/pricing via the claude-api skill at build time. System prompt template per course, editable by the creator in studio.
3. Wallet service (src/lib/ai/wallet.ts): daily allowance refresh from plan entitlements (scheduled function), atomic credit deduction per request (tokens → credits formula in PlatformConfig), hard stop at zero with top-up CTA.
4. Chat UI in the course player sidebar (AiConversation per lesson context), streaming responses, citation links back to lessons.
5. Top-up SKUs: seed 2–3 AiCreditPack rows + INR Price rows; checkout fulfillment credits the wallet (OrderItem.aiCreditPackId → wallet increment + ledger-free, platform SKU).
6. Creator controls: per-course AI-TA toggle, tone instructions, escalation ("ask in discussions") threshold.
7. Guardrails: answer-only-from-course-content mode by default, feedback thumbs on messages, abuse rate limits.
8. Cost dashboard (admin): AiUsageEvent rollups by feature/model/tenant vs. wallet revenue.
9. Flip ai-tutor FeatureFlag per-course, then globally.

Acceptance criteria

• Tutor answers cite the specific lesson used for grounding; questions outside course scope get the escalation response
• Credits deduct per message; zero balance blocks with top-up CTA; purchase credits → wallet increments via normal checkout
• Daily allowance refreshes per plan tier; downgrade lowers allowance next refresh
• Every call writes AiUsageEvent with model + token counts + credits
• Creator can disable the tutor per course

Dependencies / sequencing

• MVP M8 (entitlements) and M9 (player) required; Fermion transcription optional-but-recommended for video grounding
• Wallet service is shared by issues #3 and #5 — build the wallet here first

Start with the planned entry points in src/lib/ai/indexing.ts, src/lib/ai/tutor.ts, and src/lib/ai/wallet.ts, then review the existing AiWallet, AiUsageEvent, entitlements, and checkout schema. Confirm sequencing with M8 and M9 and the claude-api skill. Done means the listed acceptance criteria pass, including grounded citations, credit enforcement, allowance refresh, usage events, and creator disablement.