diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index c8aef7520..ffc9a4a14 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -4046,6 +4046,13 @@ model MoodEntry {
   /// whole-record by design and carries no per-domain scope. That is
   /// deliberate, not an oversight: withholding part of a record from a
   /// delegate would be a new capability, not a field select.
+  ///
+  /// None of these reaches the health score, and that too is a decision. The
+  /// WELLBEING pillar reads PHQ-9, GAD-7 and WHO-5 and cites the papers its
+  /// thresholds come from; a daily self-rated slider is a different kind of
+  /// evidence, and averaging the two would weaken the line that makes the
+  /// score worth showing to a doctor. The reasoning is written out at
+  /// `src/lib/analytics/score/wellbeing.ts`.
   moodA1        Int?      @map("mood_a1") // 0-10, pleasantness
   stressA2      Int?      @map("stress_a2") // 0-10, inverse-oriented
   energyA3      Int?      @map("energy_a3") // 0-10
diff --git a/src/lib/analytics/score/wellbeing.ts b/src/lib/analytics/score/wellbeing.ts
index a8ebe6603..1771e4b42 100644
--- a/src/lib/analytics/score/wellbeing.ts
+++ b/src/lib/analytics/score/wellbeing.ts
@@ -1,3 +1,25 @@
+/**
+ * The WELLBEING pillar reads validated instruments, and only those.
+ *
+ * PHQ-9, GAD-7 and WHO-5 over a 90-day window. Every threshold below cites
+ * the paper it comes from, which is the whole reason this pillar can be shown
+ * to a doctor.
+ *
+ * Daily mood does not feed it, and that is a decision rather than an
+ * oversight. Since v1.37 a mood entry carries a 0-10 self-rated pleasantness
+ * on most rows, including a mapped value on historical ones, so the number is
+ * available and folding it in would be a small change. It stays out: a
+ * self-rated slider moved once a day and a scored clinical questionnaire are
+ * different kinds of evidence, and averaging them into one figure that cites
+ * Kroenke, Spitzer and the WHO would weaken exactly the line that makes the
+ * figure worth anything. There is also no good answer to "why did my score
+ * drop because I logged a bad afternoon".
+ *
+ * Daily mood keeps its own surfaces — the trend page, the assistant, the
+ * briefing — where its resolution is the point. Bringing it in here would be
+ * a score decision, taken on the score line, with its own coverage rule and
+ * its own line in the explainer; it is not something to add on the way past.
+ */
 import type { Derived } from "@/lib/insights/derived/types";
 
 import type { PillarValue, WellbeingPillarInput } from "./types";