docs(api): correct the score descriptions the adaptive rule outdated

Three descriptions in the OpenAPI registry still describe the floor that
v1.38 removed, and one of them contradicts its own error-response
description two dozen lines below it.

- The score-config PATCH still said the write is refused below three
  distinct areas and one physical measurement. The route refuses the
  empty selection and nothing else; its 422 description already said so.
- The dashboard snapshot's healthScore still said the block is null until
  three eligible domains include a physiological one. It is null only
  when no pillar is readable at all.
- The pillar domain field still pointed at a three-distinct-domains rule
  that no longer exists, where what a client needs to hear is that domain
  count comes resolved on scoreBasis and must not be counted out of
  composition.

Regenerated docs/api/openapi.yaml.

The user-facing description of the score lives in the docs site's own
repository, not here; nothing under docs/ describes the composite.
This commit is contained in:
Marc-André Bombeck committed 2026-08-30 17:08:39 +02:00
1 parent 81be61b6d1
commit f29995a18c
3 files changed
+16 -13

No files matched your search

+13 -10
View File
@@ -6422,13 +6422,14 @@ paths:
tags:
- Auth
summary: Choose which pillars count toward the Health Score
description: "Replaces the recipe with the given positive selection and bumps the per-user recipe version by one. The
write is refused when the selection cannot produce a score: at least one physical measurement, and at least
three distinct areas of health. Blood pressure, glucose and cholesterol are three pillars but one area, which is
the refusal that surprises people. Accepting the write also evicts the account's score caches, so the next read
reflects the new composition rather than the previous hour's number. Optimistic concurrency: send
`baseUpdatedAt` from a prior read and the write 409s if the recipe moved since; omit it for the unconditional
write. Rate-limited to 60 writes per minute per user."
description: "Replaces the recipe with the given positive selection and bumps the per-user recipe version by one. Since
v1.38 the empty selection is the only one refused: three distinct areas of health are what the score RECOMMENDS,
not what it requires, so a one-area or two-area recipe saves and produces a score that labels its own breadth
(`scoreBasis`). Blood pressure, glucose and cholesterol are still three pillars in one area — that now decides
what the score says about itself rather than whether it exists. Accepting the write also evicts the account's
score caches, so the next read reflects the new composition rather than the previous hour's number. Optimistic
concurrency: send `baseUpdatedAt` from a prior read and the write 409s if the recipe moved since; omit it for
the unconditional write. Rate-limited to 60 writes per minute per user."
requestBody:
required: true
content:
@@ -49037,9 +49038,11 @@ components:
- delta
additionalProperties: false
- type: "null"
description: Derived cardiometabolic reference score summary. Null until at least three eligible domains include a
measured physiological domain. Additive metadata names confidence, ordered composition, the worst-pillar
band setter, score version, and why a delta was suppressed. Rest Mode annotates but never changes the score.
description: "Derived reference score summary. Since v1.38 it is null only when no pillar is readable at all: one or two
areas of health produce a score too, computed identically, with `scoreBasis` saying how broad it is — render
that beside the number rather than assuming three areas. Additive metadata names confidence, ordered
composition, the worst-pillar band setter, score version, and why a delta was suppressed. Rest Mode
annotates but never changes the score."
scoreRings:
description: "User-selected hero score rings (max 3, `selectedScoreRings` on the dashboard layout), resolved
server-side: READINESS / RECOVERY_SCORE / SLEEP_SCORE via the derived engines (module-gated like
+2 -2
View File
@@ -1345,7 +1345,7 @@ export const dashboardSnapshotResponse = z
})
.nullable()
.describe(
"Derived cardiometabolic reference score summary. Null until at least three eligible domains include a measured physiological domain. Additive metadata names confidence, ordered composition, the worst-pillar band setter, score version, and why a delta was suppressed. Rest Mode annotates but never changes the score.",
"Derived reference score summary. Since v1.38 it is null only when no pillar is readable at all: one or two areas of health produce a score too, computed identically, with `scoreBasis` saying how broad it is — render that beside the number rather than assuming three areas. Additive metadata names confidence, ordered composition, the worst-pillar band setter, score version, and why a delta was suppressed. Rest Mode annotates but never changes the score.",
),
// v1.27.7 — user-selected hero score rings (max 3), resolved
// server-side next to the health score. Additive; optional so
@@ -1951,7 +1951,7 @@ const healthScorePillar = z.object({
domain: z
.enum(["cardiometabolic", "activity", "sleep", "adiposity", "wellbeing"])
.describe(
"Which area the pillar speaks to. Three of the seven pillars share `cardiometabolic`, so a selection of four pillars can still fail the three-distinct-domains rule.",
"Which area the pillar speaks to. Three of the seven pillars share `cardiometabolic`, so four selected pillars can still be one area — which is why `scoreBasis.domains` is served resolved and must not be counted out of `composition`.",
),
result: z
.union([
+1 -1
View File
@@ -1141,7 +1141,7 @@ export const profilePaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Auth"],
summary: "Choose which pillars count toward the Health Score",
description:
"Replaces the recipe with the given positive selection and bumps the per-user recipe version by one. The write is refused when the selection cannot produce a score: at least one physical measurement, and at least three distinct areas of health. Blood pressure, glucose and cholesterol are three pillars but one area, which is the refusal that surprises people. Accepting the write also evicts the account's score caches, so the next read reflects the new composition rather than the previous hour's number. Optimistic concurrency: send `baseUpdatedAt` from a prior read and the write 409s if the recipe moved since; omit it for the unconditional write. Rate-limited to 60 writes per minute per user.",
"Replaces the recipe with the given positive selection and bumps the per-user recipe version by one. Since v1.38 the empty selection is the only one refused: three distinct areas of health are what the score RECOMMENDS, not what it requires, so a one-area or two-area recipe saves and produces a score that labels its own breadth (`scoreBasis`). Blood pressure, glucose and cholesterol are still three pillars in one area — that now decides what the score says about itself rather than whether it exists. Accepting the write also evicts the account's score caches, so the next read reflects the new composition rather than the previous hour's number. Optimistic concurrency: send `baseUpdatedAt` from a prior read and the write 409s if the recipe moved since; omit it for the unconditional write. Rate-limited to 60 writes per minute per user.",
requestBody: {
required: true,
content: {